|
|
# HDL Git Rules
|
|
|
|
|
|
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.
|
|
|
|
|
|
<!-- end list -->
|
|
|
|
|
|
- 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.
|
|
|
|
|
|
<!-- end list -->
|
|
|
|
|
|
- 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.
|
|
|
|
|
|
<!-- end list -->
|
|
|
|
|
|
- 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".
|
|
|
|
|
|
<!-- end list -->
|
|
|
|
|
|
- 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.
|
|
|
|
|
|
<!-- end list -->
|
|
|
|
|
|
- Never reference a commit in a private branch from
|
|
|
master/proposed\_master branch.
|
|
|
|
|
|
<!-- end list -->
|
|
|
|
|
|
- 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.
|
|
|
|
|
|
<!-- end list -->
|
|
|
|
|
|
- Master branch may never be rebased. Thus, it is always safe to
|
|
|
reference commits in the master branch with submodules.
|
|
|
|
|
|
<!-- end list -->
|
|
|
|
|
|
- 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.
|
|
|
|
|
|
<!-- end list -->
|
|
|
|
|
|
- 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, ...).
|
|
|
|
|
|
<!-- end list -->
|
|
|
|
|
|
- Development of large features or complicated bugfixes should be done
|
|
|
in a development branch.
|
|
|
|
|
|
<!-- end list -->
|
|
|
|
|
|
- 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.
|
|
|
|
|
|
<!-- end list -->
|
|
|
|
|
|
- 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.
|
|
|
|
|
|
<!-- end list -->
|
|
|
|
|
|
- If a change is a simple, single-commit bugfix, the responsible
|
|
|
developer may just push it directly to proposed\_master.
|
|
|
|
|
|
<!-- end list -->
|
|
|
|
|
|
- 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
|
|
|
it.
|
|
|
|
|
|
<!-- end list -->
|
|
|
|
|
|
- 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.
|
|
|
|
|
|
<!-- end list -->
|
|
|
|
|
|
- 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.
|
|
|
|