Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
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.
- Anything in the
masterbranch is deployable
- To work on something new, create a descriptively named branch off of master (i.e.
- 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:
[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
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
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).
Wikis can be updated by members directly. Non-members need to send their wanted changes via the issue tracker.