development_cycle
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.
More or less the GitHub flow:
- Anything in the
mainbranch should be deployable but we do not consider every commit as released/published. We mark published commits with a tag onmain(using semantic versioning). - To work on something new, create a descriptively named branch off of
main. - Commit to that branch locally.
- Before opening a pull request:
- if you add new functionality, extend existing test cases or add new ones, run the unit tests;
- run a static code analysis tool (
scan-build cmake -B build/ src/ ; scan-build -v cmake --build build/) to check your changes.
- When 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
main. - Once it's merged and pushed to
main, your local branch can be deleted andmainpulled again.
That is the entire flow. It's very simple, effective and works for fairly large teams.
For further details you can read Github forking.
-
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:
- build: changes that affect the build system or external dependencies
- ci: changes to CI configuration files and scripts
- docs: documentation only changes
- feat: a new feature
- fix: a bug fix
- perf: a code change that improves performance
- refactor: a code change that neither fixes a bug nor adds a feature
- revert: commits that revert a previous commit
- style: changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons...)
- test: adding missing tests or correcting existing tests
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 style to the commit message:
git commit -m "style: remove some whitespaces"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
-wswitch. -
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.
