The ImpressCMS Project has a large and active development team, and as such, need clear rules and regulations. This document defines our Commit Policy. Any developer who is given access to the ImpressCMS code repository needs to abide by these rules. Failure to respect this policy can lead to commit privileges removal.

Be informed of our discussions

Every developer need to stay informed of our discussions here. So we all need to make a commitment of reading everything that is posted on the Current and Future release forums. It is the only way we can all work together towards the same goal, and bringing synergy in our efforts.

Always document your code

That means that every function has a phpDocumentor-compliant header comment, which is both correct and understandable, states the purpose of the function and describes the parameters and return value. The same applies to class properties. The header comment for a function (or a class) is intended to be a "mini user manual" for the function that provides all the information needed to call that function, without having to examine the body of the function.

Think twice before committing

Committing something to the code repository has serious consequences. All other developers will get your changes once they are in the repository, and if they break something, they will break it for everybody. All commits will be publicly available in the repository forever. On the other hand, git allows one to revert changes, so it's possible to recover from mistakes. This is relatively easy for commits to single files but it can also be a significant amount of work for bigger changes. The baseline is: Be aware of the consequences of your commits. Take time to think about them before committing.

Never commit code that break something else

Everything you commit should not break anything else in ImpressCMS. There is nothing more inefficient than someone updating his working copy with the latest code and startup ImpressCMS to see it broke. This is a loss of time for everyone and everything needs to be done to prevent this from happening.

Test your changes before committing

Run the relevant parts of the validation suite to make sure that the changed code behaves as desired. ("make valid" in the sandboxes).

Double check what you commit

Do a "git fetch" and a "git merge" before committing. Take messages from git about conflicts, unknown files, etc. seriously. The "svn status" will tell you what you will be committing. Check if that's really what you intended to commit.

Always add descriptive log messages

Log messages should be understandable to someone who sees only the log. They shouldn't depend on information outside the context of the commit. Try to put the log messages only to those files which are really affected by the change described in the log message. In particular put all important information which can't be seen from the diff in the log message.

Respect ImpressCMS Coding Conventions

The code you commit must always adhere to the ImpressCMS Coding Standards. These include rules for coding, naming, commenting, formatting, and documentation.

Respect Branch-when-needed system

About branching, we are using the "Branch-when-needed" system :

• Users commit their day-to-day work in the active branch
• Rule #1: the active branch must compile and pass regression tests at all times. Committers who violate this rule are publicly humiliated
• Rule #2: a single commit (changeset) must not be so large so as to discourage peer-review.
• Rule #3: if rules #1 and #2 come into conflict (i.e. it's impossible to make a series of small commits without disrupting the trunk), then the user should create a branch and commit a series of smaller changesets there. This allows peer-review without disrupting the stability of /trunk.

See also: Demo for branching in git

Respect Release Procedures

Respect ImpressCMS Release Procedure

Consult before making large changes

Respect the policies of application and library maintainers, and consult with them before making large changes. Source control systems are not a substitute for developer communication.

Announce big changes

When you plan to make changes which affect a lot of different code in SVN, announce them on the developer mailing list in advance. Changes which affect a lot of code in SVN, like making use of a new feature in the libs, might break other code even if they look trivial, e.g., because an application must also compile with older versions of the libs for some reasons. By announcing the changes in advance, developers are prepared, and can express concerns before something gets broken.

Take responsibility for your commits

If your commit breaks something or has side effects on other code, take the responsibility to fix or help fix the problems.

Don't commit code you don't understand

Avoid things like "I don't know why it crashes, but when I do this, it does not crash anymore." or "I'm not completely sure if that's right, but at least it works for me.". If you don't find a solution to a problem, discuss it with other developers.

Don't commit controversial changes

Don't abuse your git account to push in changes with which other developers disagree. If there are disagreements over code changes, these should be resolved by discussing them on the mailing lists or in private, not by forcing code on others by simply committing the changes to SVN.

Always reference ticket number

Everything that is committed needs be linked to a ticket number in the issue tracking system. Be sure to include this ticket number in your commit log message, as well as a summary of the ticket and code you committed. While the ticket number is mandatory in the log message, it is hardly enough and always need explanations for easier understanding by others of what was committed. It should be clear from the log message what has been changed without looking at the bug report.

Make "atomic" commits

Git has the ability to commit more than one file at a time. Therefore, please commit all related changes in multiple files, even if they span over multiple directories at the same time in the same commit. This way, you ensure that the repository stays in a compilable state before and after the commit.

Don't mix formatting changes with code changes

Changing formatting like indenting or whitespaces blows up the diff, so that it is hard to find code changes if they are mixed with re-indenting commits or similar things when looking at the logs and diffs later. Committing formatting changes separately solves this problem.

All commits are to be reviewed

All commits will need to be reviewed according to our Commit Review Policy.

Appendix: Special keywords in git commit messages

You can use commit comments to link your changesets to Assembla tickets, and add comments to tickets or change their status.

Reference

This policy was originally copied from KDE Commit Policy and GenPar Commit Policy and modified for ImpressCMS. We thank the people who originally created these policies as they came really handy for our project!