Skip to content

  • Projects
  • Groups
  • Snippets
  • Help
    • Loading...
  • Sign in
O
OHR Support
  • Project
    • Project
    • Details
    • Activity
    • Cycle Analytics
  • Repository
    • Repository
    • Files
    • Commits
    • Branches
    • Tags
    • Contributors
    • Graph
    • Compare
    • Charts
  • Issues 97
    • Issues 97
    • List
    • Board
    • Labels
    • Milestones
  • Merge Requests 0
    • Merge Requests 0
  • Wiki
    • Wiki
  • image/svg+xml
    Discourse
    • Discourse
  • Members
    • Members
  • Collapse sidebar
  • Activity
  • Graph
  • Charts
  • Create a new issue
  • Commits
  • Issue Boards
  • Projects
  • OHR Support
  • Wiki
  • Repository use

Repository use

Last edited by Alessandro Rubini Dec 11, 2013
Page history

Policies about Repository Use

These topics have been discussed at the WR workshop in Madrid, on Nov
27-28 2012, and later refined on Dec 2013, on the wr-dev list and
private email.

This page is not specific
to White Rabbit but generic about development on ohwr.org (both
software and gateware). Please link it from other projects when
it makes sense, its location won't change.

The Resources and the Problem

Unfortunately, the engine that drives ohwr.org only supports one
repository per project. This means that concurrent development
must work on a single repository, where stable releases and unclean
tests coexist.

To be able to freely experiment, people needs 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.

On the other hand, 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.

The Tools

Development (i.e., volatile commit identifiers) may just happen
on other repositories, outside ohwr. This means github.com,
gitorious.com or one's own machine with ssh access for mates. However,
the overhead for users is not considered worth the effort.

Therefore, we can count on the following tools to implement a
sensible policy. Most users should already know them:

  • Named branches. Different names have different meanings: people
    should know that names like "master" or "stable-2012-10" are different
    from "devel-rubi-121101" or "testing-new-pll".
  • Renames. Renaming a branch doesn't change any commit identifier.
  • Tags. If a commit is pinned by a tag, it won't disappear until the tag
    is removed. The tag can be like "v2.1" or "projectname-v2.1". The
    latter convention allows to tag external projects when needed
    (for example, the fine-delay projects used tags in spec-sw and
    zio to pin down the commits it relied on).
  • Submodules. A submodule makes the supermodule refer to a
    specific commit of another project. You must ensure that that
    very commit must remain available in the future.
  • Merges. When a merge happens, the commit identifiers of both branches
    will remain.
  • Rebases. A rebase, interactive or not, changes all commit
    identifiers. Previous numbers are lost, and you can't go back
    to that specific checkout. This happens even if you only rephrase
    a commit message.

The Rules

Based on the above, we defined a set of rules for best collaboration
between developers. We identified two different set of repositories:
the ones that are fast moving, where different people concurrently
commit serious code and users rely on the master branch, and "slower"
repositories, where we make official releases any now and then, and
introduction of new features is somewhat slower.

The two set of rules are not conflicting; the main difference is
the role of the "proposed_master" branch.

Rules for "fast" repositories (e.g.: wr-cores, general-cores).

  • All developers work against a branch called "proposed_master".
  • New features are developed either in a local proposed_master or in a
    branch and only pushed to ohwr/proposed_master when they are
    done+tested.
  • The repository maintainer moves proposed_master to master when it
    seems in a good state.
  • When a release happens, a branch of master is created by the
    repository maintainer at that time.
  • The repository maintainer backports critical bug-fixes from
    proposed_master to the released branch.

Rules for "slower" repositories (e.g. wr-switch-sw, spec-sw).

  • Master is holy for normal developers: only the maintainer should push
    to master, or approve others to push specific commits.
  • Master is holy for the maintainer: no rebase is ever
    permitted. Everybody can base their development or fetch a
    submodule from a commit that is an ancestor of master. (I'd add
    a special exception, allowing the maintainer to change master right
    after a wrong push, like giving an half-an-hour window; this means it's
    safe to base on commit that are at least a little old).
  • All development must happen in private branches.
  • Before requesting a merge to master, consider rebasing to the
    current tip of master. This is a controversial point, and different
    people have strong and differing ideas. Please consider both options
    and choose what to follow case by case.
  • Git submodules must only refer to master commits, tags or
    branches of stable forks (e.g., a backport).
  • Nobody can remove branches or tags by other developers, unless
    authorized by said developer.
  • If your branch or tag needs to be persistent, because it is a
    submodule of something else, name it clearly as stable or
    important stuff. This will save you from being asked by others
    to remove them. You can rename a branch without losing
    information or commits.
  • 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 non-precious 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.

Keeping backups

I (Alessandro) strongly suggest to keep a backup of your
development on your personal machines, so any rebase made by
others won't lose your commits (such rebases are errors, for
sure, but they still may happen). See Local-GIT-Backups
for details.

Thanks

Thanks to all WR developers (too many at this point to list),
who helped reaching agreement, after we faced the unavoidable issues
of imperfect commits and rebases.

Clone repository
  • Administrator guide
  • Documents
  • Folder structure example
  • Gitlab migration of ohwr faq
  • Home
  • Local git backups
  • News
  • Project structure guidelines
  • Project guidelines
  • Project re structure tips
  • Project review by ht volunteers
  • Repository use
  • Repository use2
  • Documents
    • Ohr logos
    • Ohwr new design visuals
More Pages

New Wiki Page

Tip: You can specify the full path for the new file. We will automatically create any missing directories.