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.
Third Parties¶
Simply checkout this SVN folder and place the contents of the folder in your GIFT/external/ folder.
https://_hidden_/ThirdParty/Windows-32bit
To verify your third parties are placed correctly you should have this file:
GIFT/external/ant/README
More details instructions are here.
SVN Tools¶
We recommend using TortoiseSVN for interacting with the SVN repository.
Quick Start: SVN checkout a GIFT branch¶
An SVN checkout is basically copying the files from the SVN server and placing them on your computer.
- Install TortoiseSVN (https://tortoisesvn.net/)
- It is recommended that you create a new folder to work in. The new folder should be created in a path that doesn't have too many characters in the path name already.
- E.g. C:\work\*GIFT*\ or C:\*GIFT*\
- Your Windows Desktop is not recommended because the path to your Desktop is already long to begin with, e.g. C:\Users\mhoffman\Desktop\.
- Right-click in the new folder and select 'SVN Checkout...'
- Checkout dialog form values:
- Enter the URL of the GIFT branch you want to checkout in the 'URL of repository' textfield.
- The 'Checkout directory:' should already be populated. No need to change it.
- The 'Checkout Depth' should already be 'Fully recursive'. No need to change it.
- 'Omit externals' checkbox should be un-checked by default.
- The 'Revision' value should be 'HEAD revision' (unless a specific revision in the past is needed)
- Click the OK button.
- If your GIFT SVN credentials have not been saved you will be asked to enter them.
- A dialog should appear showing the file-by-file transfer to your computer.
- If the SVN checkout fails, perform an SVN Update in the top level directory that also contains a '.svn' hidden folder. For example if I checked-out a branch called 'Foo' to 'C:\GIFT\' the hidden directory 'C:\GIFT\Foo\.svn\ should exist. Perform the SVN Update in the 'C:\GIFT\Foo\' directory.
Next Steps - now that you have performed an SVN Checkout of a GIFT branch you will need the third party libraries before attempting to use that GIFT instance. Instructions can be found here.
Quick Start: SVN Update¶
An SVN Update is similar to an SVN Checkout, however an SVN Update can only be performed once an SVN Checkout has made it far enough to get the '.svn' folder fully created.
- Right-click in a folder and select 'SVN Update'
- If you see 'SVN Checkout...' in the right-click menu than you haven't successfully performed an SVN Checkout or you are trying to SVN Update in the wrong location.
Quick Start: SVN checkout third parties¶
The third parties are in a separate location. Assuming you followed the quick start to SVN checkout a GIFT branch:
- Go to the folder you created to work in.
- E.g. C:\work\*GIFT*\ or C:\*GIFT*\
- Right-click in the new folder and select 'SVN Checkout...'
- Continue to follow the SVN Checkout a GIFT branch procedure but this time use the Third Party library URL you were given as the 'URL of repository' value.
After third party checkout: copy the files inside the 'Windows-32bit' folder to GIFT\external\. You will know you did this correct if GIFT\external\activemq\ is a folder that exists in your GIFT folder structure.
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.