Subversion Repository Code of Conduct

[edit]

Why have this document?

Our Subversion repository is wonderful in many ways. To keep it wonderful, committers should follow a few simple guidelines.

[edit]

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).

Also see Subversion Repository Layout
[edit]

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.
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.
[edit]

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.

[edit]

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."

[edit]

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).

[edit]

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

[edit]

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.

[edit]

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.

[edit]

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
[edit]

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.

[edit]

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
[edit]

Commits to a module

Be sure to include the module id in the message. 

formentry module: Adding functionality X - #123
[edit]

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.

[edit]

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.

[edit]

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.

To allow patch authors to be properly credited in an automated fashion, attribution should be on a separate line starting with "author:" followed by trac username(s) of patch contributor(s) separated by commas.

For information about submitting patches to OpenMRS, see our pages on patches.

[edit]

Creating a branch

Be sure to include the branch name and the username of its intended user 

Creating branch dictionary_import for bwolfe
[edit]

Creating a module

Be sure to include the module's id and the username of the intended user 

Creating module formentry for bwolfe
Retrieved from "http://openmrs.org/wiki/Subversion_Repository_Code_of_Conduct"