GIFT SVN Repository Rules and Guidelines¶
NEW USERS PLEASE READ AND UNDERSTAND THE RULES SECTION
Internally we use an SVN repository to manage various development efforts on GIFT. This page describes best practices for those that have access to the repository.
General Structure¶
In the GIFT SVN there are branches, tags and trunk. Most development is done in branches.
Trunk and branches (when created) do not have third party libraries or courses. These are stored in another location in the SVN. Once you have SVN access to a branch, for example, you will also have access to the third party library in SVN. Simply checkout that SVN folder and place the contents of the folder in your GIFT/external/ folder.
Third Parties
https://_hidden_/ThirdParty/Windows-32bit
To verify your third parties are placed correctly you should have this file:
GIFT/external/ant/README
SVN Tools¶
We recommend using TortoiseSVN for interacting with the SVN repository.
Rules¶
EVERY USER WITH SVN WRITE ACCESS MUST READ AND FOLLOW THE FOLLOWING RULES.
SVN commit messages¶
Please provide useful commit messages that can be used in the future to help determine the purpose of the commit.
Not useful:
"latest changes for GIFT"
"commit from Mike"
"fixed a problem"
Useful:
"Added logic to allow users to select multiple survey items in the survey composer using the CTRL key. Added logic to allow selected survey items to be copied via a copy button on each question container widget. Added some UI logic to start flushing out an interface for copying survey items from other surveys."
If you are also using gifttutoring.org Issue tracker than you should associate all SVN commits with the Issue ID. This will enable Redmine to display the changes made in svn.
Example:
"IssueID #2880 - moved larger question type creation logic into methods; now handling slider to matrix creation logic"
The syntax 'IssueID #<issue number> ' is specific to Redmine and can appear anywhere in the commit message.
Identifying core files not to commit¶
Third Parties¶
Third Party files (i.e. those files found in GIFT/external) are not suppose to be committed to trunk or branches. For svn tags that correspond to GIFT release the third parties will be committed to that tag as part of the built, configured and historical archive of that release.
If you are adding a new third party library to GIFT please consider the following:- Until your development branch is merged back into trunk your NEW third party libraries can be committed to your branch in the GIFT/external folder.
- The caveat here is if your third party library can not be released to the public for various licensing reasons. We try hard to integrate libraries that we can freely distribute to the GIFT community.
- Don't commit Third parties provided by GIFT.
- Update (and commit) the Third Party README file with license information about your third party library (i.e. GIFT/external/ThirdParty.README.htm)
- If possible try to compress or link to the libraries documentation rather than including it in the commit.
- If there is more than one file for your third party please place it in a folder that has a useful name.
Domain folder¶
The Domain root level folder mainly contains course folders. It also contains other folders that are used for Importing courses, Exporting courses, handling files temporarily and runtime copies of courses.
In most circumstances the only time you might commit something in the Domain folder is a course that was authored to demonstrate some new feature in your development branch. These course folders will either reside in either the following:
- Domain/workspace/Public/
- Domain/workspace/<username>/
Please keep in mind that SVN does a good job of compressing changes to text type files (.txt, .java, .cpp, ...) but not binary type files (.dll, .jar, .zip, .mp4, .mov, .jpg, .png, ...). Therefore you should only commit when necessary to share your changes with others or when significant progress has been made.
New files¶
If you find a new file in your GIFT folder structure that doesn't appear to be in SVN and it isn't in a course folder nor is it a file you created, chances are you shouldn't add it to SVN. It is most likely the result of installing GIFT, building GIFT or running GIFT.
One example of this is the build output in:
- GIFT/bin
- GIFT/build
In a GIFT release, GIFT is delivered fully compiled and therefore the corresponding svn tag has all of the GIFT created jars committed to svn. For branches and trunk this isn't necessary. The only exception is the GIFT installer. The GIFT installer jar(s) are in SVN in order to allow someone to checkout a GIFT branch and then run the GIFT installer which will also compile GIFT for you.
Merging with latest GIFT development¶
It is very common for development being done in a svn branch to need newer GIFT functionality to be merged into it. In most circumstances Dignitas will be asked to perform this operation as we are aware of the various changes being made to GIFT. If you perform the update/merge than we suggest that you separate that commit from changes made for the effort you are developing in the branch. This will make it easier to identify, review and merge the changes from the branch back into trunk in the future.