Skip to content


Manlio Morini edited this page May 26, 2017 · 12 revisions


This page details the rules that need to be followed when contributing code or documentation to the project.

The first requirement is that either you and/or your employer needs to sign the individual or corporate contributor license agreement. Which one is needed depends on your particular case.


GitHub flow!

  • Anything in the master branch is deployable
  • To work on something new, create a descriptively named branch off of master (i.e. new-oauth2-scopes)
  • Commit to that branch locally and regularly push your work to the same named branch on the server
  • When you need feedback or help, or you think the branch is ready for merging, open a pull request
  • After someone else has reviewed and signed off on the feature, you can merge it into master
  • Once it is merged and pushed to master, you can and should deploy immediately

That is the entire flow. It is very simple, very effective and works for fairly large teams.

(read Scott Chacon's great article for further details)

General guidelines for code commit

  • Commit and push early. Do not delay pushing out your changes. The sooner that we see your code, the sooner we can spot problems, offer suggestions, and help you.

  • Make small, logically coherent commits. Each commit should be one coherent (though, perhaps incomplete) piece of work. For example, a single commit might add a new class with a rough outline of its public methods, perhaps with a bunch of inlined TODO comments. You do not want to mix many kinds of changes into one commit.

  • Strive to commit code that compiles. Code that does not compile is difficult to review. However, it is okay if sometimes your code does not compile.

  • Include meaningful commit messages. Always include a commit message that explains as many of the changes you have introduced as possible. Someone will review your code, and it is much easier to interpret a commit if the commit includes a high level rationale for the changes. An example message is short and to the point (see also Writing Good Changeset Comments).

    Don't end the summary line with a period - it's a title and titles don't end with a period. Always leave the second line blank. Line break the commit message (to make the commit message readable without having to scroll horizontally).

  • Please prefix all commit summaries with one (or more) of the following tags. This should help others to easily classify the commits into meaningful categories:

    • [FIX] bug fix;
    • [ADD] new feature or extended functionality;
    • [DOC] for all kinds of documentation-only related commits;
    • [REF] refactoring that doesn't include any changes in features;
    • [FMT] formatting only (spacing...);
    • [TEST] related to test code only.
    • [MAK] repository related changes (e.g. changes in the ignore list)

    These tags are always the first thing in the commit message and are followed by a brief description and/or the issue-id from the issue tracking system, if it exists.

    There is a useful template for commit messages. Run

    git config commit.template <path-to-template-file>

    to put commit template for this project only (used every time you do git commit).

  • Do not mix formatting changes with code changes. Some diff tools are sensitive to whitespaces, which makes it difficult to compare files that are formatted differently. For example, every line might be highlighted as changed/new, even though the code is identical. Make two separate commits, one to change the code formatting (i.e. how the code looks) and another to make changes to the code.

    When you commit formatting changes add the prefix [FMT] to the commit message:

    git commit -m "[FMT] Removed some whitespace"

    Messages with this keyword could then be ignored when generating change logs.

    As a remainder you can compare two revisions and ignore whitespaces with the -w switch.

  • Give the issue number preceded by a number/pound/hash sign (#) if the change you are committing relates to an issue. This convention is interpreted by the commit log to provide a link back to the issue (and much more).


Wiki updates

Wikis can be updated by members directly. Non-members need to send their wanted changes via the issue tracker.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.