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

Code in custom-builds is up to the specific contributor, but and is not for developing, see custom-builds

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.
  • 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
  • May create a branch for themselves or partial committers (see #Creating a branch for commit comment examples)
  • Can request a partial committer be promoted to a full committer.
Partial Committers
  • Should commit only within their area(s) of expertise.
  • Are welcome to make straightforward, obvious fixes to the trunk.
  • May create a branch for themselves for a ticket or with approval from a full committer (see #Creating a branch for commit comment examples)
[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. See also Module Licensing

Module developers are encouraged to follow Subversion's suggested directory layout: 

 /openmrs-modules/
   yourmoduleid/
     trunk/
     branches/
     tags/

The latest code goes under the trunk folder, the branches folder is used for trying out changes separate from trunk, and tags are copies of trunk at the time of a particular release. If you are not planning on a release cycle at first, we still encourage you to put your code into a "trunk" folder, since many modules eventually evolve to needing this structure. If you need to change to a branches/tags/trunk structure, see Module Branching.

Module authors are encouraged to mimic the OpenMRS versioning style: major.minor.maintenance -- e.g., 1.5.2.

Modules that work with a specific version of openmrs are encouraged to use 1.5.x-compatible or 1.4.x-compatible as the branch name inside their module.

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]

Custom Builds

A space for custom builds is provided within the repository to facilitate the process of combining specific releases with features from subsequent releases and/or unreleased patches. While applying patches to a specific release may often require some small tweaks to the code to accommodate interval changes, we do NOT want people doing development within these custom builds. All development should occur within patches or branches. Developers who run off and start using a custom build to commit all their new code risk being publicly castigated and/or losing their commit rights.

Each custom build should have a README file in the root folder describing what changes are in that build. This allows anyone else that might want to use those same features to quickly know how that build is compiled.

Each custom build is suggested to have a set of patches in the repository that have been applied. This helps when upgrading and is another tool that gives other developers insight into what that custom build contains.

All new code that is committed to custom-builds should get a ticket that either points at the changeset or gets the patch attached to it. This will help to make sure that a fix isn't going into a custom-build and then forgotten about. The rest of the community suffers when this happens.

[edit]

Cleaning up a module folder, branch, or contrib

  1. Review the modules (or write a script) that shows all modules not touched within the last two years.
  2. Get list of modules downloaded or "checked for updates" in the module repo in the last 1 year.
  3. Delete from the repo all modules that are in the first list but not in the second
  4. Add a note to the wiki pages for each module (that we can find) that was deleted about its automatic pruning and where to find the last working svn code.
[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:
  • The ticket id is optional, as there could be no trac ticket associated with the fix. 
Fixing feature XXX - #123

where "Fixing feature XXX" is a descriptive sentence about the error/function being corrected and 123 is the trac ticket id.

[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
  • Include the revision numbers that are the start and end of the merge. (The ending merge number is very important when re-merging later) 
dictionary_import: Merging trunk to dictionary_import [123]:[234]

Where 123 and 234 are the revision start and end numbers for the merge.

[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)
  • Be sure to give attribution to the username of the person that wrote the patch 
dictionary_import: Adding feature XXX . see ticket #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 as specific as possible in your initial commit comment. Commits creating new branches are sent to the developers mailing list.
  • Be sure to include the branch name and if applicable, the username of its intended user
  • For partial committers, include the username of the approving full committer
  • For branches based on tickets, put ticket number in branch name
See requesting subversion repository access for how to request a new branch.
Creating dictionary-import branch to add web services throughout the api to allow for concepts and forms to be passed from a parent server to a child server.

Creating foo-bar branch to do XX features so that YY functionality.  Approved by mseaton

Creating ticket974-liquibase branch to add liquibase into openmrs to replace the .sql files and the manually update-to-latest-mysqldiff.sql file.
[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"