Skip to content, Skip to search


Coding style

288 bytes added, 06:33, 4 November 2014
SCM history: clarify what makes a "thorough" commit message
* We provide a permanent, stable master branch (i.e., no force pushes).
* We try to write thorough and [ well-formatted] commit messages. As a rule of thumb: relevant information that cannot be deduced easily from the patch itself should be provided in the commit message's ''body'', e.g. what other approaches were tried first and why they did not work, a motivating blurb why the patch is desirable, or links to discussions.
* In general, we prefer merging to rebasing, so that individual commits continue to reflect what was actually the true development history (i.e., what was tested and working at the time). That said, we do use rebasing sometimes on topic branches to keep our commits well organized and easy to understand.
* We use topic branches for large feature additions and complex code changes, and purge them promptly once merged to master. We prefer to make explicit merges (i.e. with <code>--no-ff</code>) to document the purpose of each merged branch.
* In the case of unfinished work at the conclusion of a coding session, we commit it with the subject ''WIP'' and push to the topic branch. (Calling <code>git reset HEAD^</code> next time makes it easy to pick up the work from there.) Doing this reduces the chance of lost work, and makes it easier for other programmers to collaborate during development.
* We avoid monster commits (with commit messages like "Many changes to several subsystems") in favor of well-separated, modular commits with one conceptual change at a time. Git's staging area feature makes this much easier (e.g., <code>git add -p</code>). Granular commits have many advantages; e.g., <code>git bisect</code> becomes much more useful for understanding mysterious bugs.
== Javadoc and comments ==
Bureaucrat, incoming, administrator, uploaders