Subversion Repository Code of Conduct
Why have this document?
Our Subversion repository is wonderful in many ways. To keep it wonderful, committers should follow a few simple guidelines.
Repository Overview
Code in the trunk should always build but does not always have to run smoothly.
Code in other branches does not have to compile or run. It is all up to the branch creator/maintainer(s).
Code in module branches does not have to compile or run. It is all up to the module source creator/maintainer(s).
Code in contrib branches does not have to compile or run. It is all up to the specific contributor(s).
Commit Access
There are three types of commit access: admin, full, and partial. Developers without commit access can submit code through patches (via the developers list, attached to a ticket, or via a committer).
- Admin Committers
- Only used during a release cycle. The role of the admin(s) at this time is to tag the trunk codeh, generate the war file, update the install file, and post (release) the files.
- The current admins are Ben Wolfe and Justin Miranda
- Full Committers
- May commit to any part of the subversion tree, may commit patches to trunk by outside developers, and may request a partial committer be promoted to a full committer.
- Partial Committers
- Should commit only within their area(s) of expertise. Partial committers are welcome to make straightforward, obvious fixes to the trunk.
How to Become a Partial Committer
The support of a full committer is enough to become a partial committer. Usually, this will happen when a developer has contributed several patches to a full committer and that full committer feels it would be easier for the developer to simply apply their changes directly to the repository. The sponsor should observe the first few commits of new partial committers to ensure things go smoothly.
How to Become a Full Committer
After contributing a few non-trivial patches or enhancements to the system, a developer can be nominated for full commit access. Decisions on granting full commit access are based on the consensus of existing full committers. As described by the Subversion group, "the primary criterion for full commit access is good judgment."
Committing to Trunk
Full committers can commit to trunk; this should be coordinated with other developers, especially the admins.
Partial committers should not commit to trunk, but are allowed to commit obvious and straightforward bug fixes, or minor self-contained enhancements to existing features directly into trunk.
All other developers may submit bug-fix patches by attaching a patch file to a trac ticket. Any full committer may apply these patches to trunk. Full attribution should be given in the commit message (see commit comment conventions for formatting attribution).
Any major feature additions or code overhauls should be submitted to a branch. Branching is quick, easy, and if done right, low-bandwidth -- don't be afraid of it (see Subversion Branching and Merging Techniques).
New Features
All new features should be developed in a branch. This allows the developer to adhere to the policy of committing early and often much more easily than if the feature were developed directly on trunk (see Subversion Branching and Merging Techniques).
All developers are expected to watch source code that is committed (e.g., via rss) and give the one who is committing feedback. The committing developer must be open to suggestions and constructive criticism.
When a feature has been fully developed and tested, it can be merged back into trunk by a full committer. Merging "permission" should be acquired from the other full-access developers prior to the merge (see Subversion Branching and Merging Techniques).
We welcome outside developers to become partial access committers. For outside developers that would like to contribute something larger than a bug fix, a branch can be created and read/write access given to that developer. If you would like to have a branch created for you see Developers#Requesting_Subversion_Repository_Access
Modules
All module code will be placed under the /openmrs-modules folder in the repository. The name of the folder for the source code will be the name of the module id. The code stored in the repository must be open source, but does not have to be under the OPL.
To request space for a new module see Developers#Requesting_Subversion_Repository_Access.
Changes to Database Model
All changes to the data model should be discussed by all interested developers and vetted through the developers mailing list before changes reach the trunk.
If an immediate data model change is required, the change should take place in a branch, interested developers notified, and the change placed on the next week's developers' conference call agenda.
Commit Comments
This section outlines the different scenarios and sections in which commits occur. Find the one that best matches yours and follow that.
Note that code commit comments and ticket comments are linked in trac via key characters:
- Link to a specific revision with braces or the 'r' character: [1234] or r1234
- Link to a specific ticket number with the pound sign: #123
Commits to trunk
Note that these should be smaller bug fixes. See above section for when to use branches. You do not have to include the word "trunk" in your message:
Fixing XXX - #123
where "Fixing XXX" is a descriptive sentence about the error/function being corrected and 123 is the trac ticket id. The ticket id is optional, as there could be no trac ticket associated with the fix.
Commits to a branch
Be sure to include the branch name in the message.
dictionary_import branch: Fixing XXX - #123
dictionary_import branch: Adding functionality X
Commits to a module
Be sure to include the module id in the message.
formentry module: Adding functionality X - #123
Merges from trunk to a branch
Aka: updating a branch to the latest trunk code
dictionary_import: Merging trunk to dictionary_import [123]:[234]
Where 123 and 234 are the revision start and end numbers for the merge. Including the revision numbers here comes in very handy later when you have to do another merge from trunk.
Merges from a branch to trunk
Merging dictionary_import to trunk [123]:[234]
Where 123 and 234 are the revision start and end numbers for that merge.
Applying patches to trunk and other branches
Be sure to include the name of the branch if applicable and the username of the person that wrote the patch
dictionary_import: Applying patch #123 author: bwolfe, hhornblower
Where 123 is the ticket the patch came from and bwolfe is the authors trac/svn username. Be sure to attribute the patch author(s) in the comment so we can track and properly attribute contributions.
For information about submitting patches to OpenMRS, see our pages on patches.
Creating a branch
Be sure to include the branch name and the username of its intended user
Creating branch dictionary_import for bwolfe
Creating a module
Be sure to include the module's id and the username of the intended user
Creating module formentry for bwolfe
