Guidelines for Committing Code to DSpace SVN

All of the below guidelines are just suggestions. They are not meant to create additional "red tape" during the normal development process. If you find they are getting in the way, let us know, we can always change them! Development processes and best practices change over time, and these guidelines should be no different.

General Guidelines for Committing

Use JIRA to track your changes
- Ensure there is an issue describing the fix/improvement/feature in JIRA (If this is a minor typo fix, or an obvious bug, you need not add a JIRA issue – use your judgment on whether this fix is worth tracking in JIRA or not)
Share your code before committing
- If this is a more significant fix/redesign, you may want to use the SVN sandbox to manage your code (rather than dealing with large patches, etc). You also may want to document your work on the Wiki, and link both of these back to the JIRA issue.
- If this is a smaller bug fix, you could just work on your code locally and generate a patch to attach to the JIRA issue
Code "approval" processes
- General Rule of Thumb: Committers are trusted developers. Use your best judgment on whether or not you feel a particular piece of code should be approved before committing. The below guidelines are just suggestions and they may not apply to all scenarios:
- If this is a small, obvious fix (typo/improved comments/obvious bug), just commit it immediately. This is the exception to all other rules – there's no reason to add a JIRA issue for every typo or obvious fix, and no reason to wait around for approval to commit it.
- If this is a bug/issue fix, we generally try to run it by one other committer. If there is any doubt, feel free to run it by others or ask to have it added to the agenda of the next developers meeting.
- If this is a new feature, we generally try to run it by a few committers (or bring it up in a developer meeting, if it's a larger change). The only reason we suggest to run it by more than one committer is that oftentimes others may be able to provide additional suggestions or configurations that may be worth investigating.
Document your code early & often
- New features/improvements need to come with documentation, otherwise we won't be able to accept them. Keep this in mind while you are developing, and use the Wiki or JIRA to start your documentation early on (it'll make it easier on you in the long run)

"Trunk" Committing Rules

By "Trunk" we are not only referring to /dspace/trunk in SVN. We're also referring to the "Trunk" of any other production-quality, out-of-the-box modules within SVN.

The SVN Trunk is one of the few places that needs to remain well managed. As many committers work out of it on an almost daily basis, it can be detrimental to us all if in-complete or extremely buggy code is committed. Obviously, mistakes happen (and we've all made them), so don't worry if you accidentally commit something you didn't mean to (just try to roll it back as soon as you notice it). Here are the few rules we try to follow when committing code to Trunk:

No incomplete features in "Trunk", ever.
- If you are in-progress on a feature, create an SVN sandbox or DSpace branch area to work on it, and pull it over to Trunk once it has been completed and is ready for testing & release. This will hopefully help us to avoid encountering a situation where we need to revert a large, unfinished patch at the last moment.
- Modules which do not reside in DSpace "Trunk" (e.g. http://scm.dspace.org/svn/repo/modules/) should also follow this rule. If there is major rework to be done on a module, create a "branch" to do that work and migrate that branch back to the Module's Trunk once it is ready for release.
All new features must have documentation before committing to Trunk.
- If a feature has no documentation, it should not be committed to Trunk until there is some minimal documentation (minimal documentation includes documenting all configuration options). This will help us all ensure that Documentation is ready by the time we get to the next release, and hopefully lessen the time that any one person has to spend cleaning up or rewriting documentation.