These rules, courtesy of Wesley (with small modifications by Tom and
Alessandro), apply to all HDL Git repositories in the OHWR.
The Resources and the Problem
We need persistent commit identifiers, especially when a project is
used as a "git submodule" of another project. If one commit is used
as a submodule, we cannot risk losing it.
On the other hand, to be able to freely experiment during
development, people need to change history. For example, to fix a
bug in an already-committed patch, or to change a commit message to
make it more useful to others.
Finally, different groups working on the same code base need to be
able to push commits and reference those commits. As these groups
have different schedules, they must be able to work independently.
Nevertheless, an official version should be available at all times
under the "master" branch.
There are three types of branches: the master branch, the
proposed_master branch (for staging changes to be committed to the
master), and private branches.
Private branches may only be rebased, pushed, or destroyed by the
person who created them or with his/her permission. To keep track of
who is responsible for which branch, it is recommended to use the
Private branches are not only meant for development purposes.
Developers can keep their own master/release/staging branches,
exchange them freely and request a merge to the master. Maintainers
will never modify the private branches without permission of the
Never reference a commit in a private branch from
Master branch is a special public branch which is managed by a
dedicated maintainer. Only the repository maintainer(s) may commit
to the master branch.
Master branch may never be rebased. Thus, it is always safe to
reference commits in the master branch with submodules.
Stable releases are identified as tags in the master branch, and
come with documentation, news & status updates on the Wiki pages of
the OHR project.
proposed_master is used to stage the commits to the master. It's
regularly merged after extensive testing. If a rebase of
proposed_master is ever needed (due to exceptional circumstances
such as copyright-infringing code), it must be agreed between all
Only merge a change to master/proposed_master branches after it is
complete and tested! Confirm that it builds using as many tools as
possible (Modelsim, ISE, Quartus, ...).
Development of large features or complicated bugfixes should be done
in a development branch.
When preparing a private branch for merge to the proposed_master
branch, consider first rebasing the private branch against the
proposed_master branch. Please also tidy up the commit history
using "rebase -i" to seperate logic changes into logical and
compilable commits. Git repository is not your Dropbox account.
When merging a private branch to proposed_master branch, prefer to
use "merge --no-ff" so that the merge itself is a trackable commit.
Without this, we cannot identify who did the merge and when.
If a change is a simple, single-commit bugfix, the responsible
developer may just push it directly to proposed_master.
If a commit is for some reason unacceptable, but alerady in master
branch, make an explicit follow-up commit reverting it. Explain in
the commit why this was done. Do not rebase or cherry pick to remove
To keep development as tightly integrated as possible, master branch
should be updated on a regular basis.
Integration with build
Whenever a binary is shipped (software or vhdl), it should claim
which commit it was compiled from -- for example, for software we
can use "git describe" to get a useful string. Binaries from
uncommited code or development commits should be only used
temporarily for experimenting.
If your repository refers to external binaries, make sure the name
of those binaries is not generic. If later releases of your
repository will refer to different binaries, you can't just
overwrite them, or users running the previous version will get in