Skip to content

H
HDL Core Lib

Hdl git rules

Last edited by Tomasz Wlostowski
Page history

HDL Git Rules & Recommendations

These rules, courtesy of Wesley (with small modifications by Alessandro and Tom), shall 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.

The Rules

  • 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 format "owner-purpose".
  • 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 owners.
  • Never reference a commit in a private branch from master/proposed_master branch.
  • 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 parties.

Recommended Practices

  • 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 separate 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 already 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 it.
  • 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 gateware), 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 uncommitted 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 trouble.