From Archivematica
Revision as of 17:46, 23 March 2017 by Hbecker (talk | contribs) (Copied from internal wiki docs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Main Page > Development > Merging & Branches

Archivematica branching guidelines

Guidelines on when to create branches for new development in Archivematica projects. Short answer: always create branches!

  • All development work happens in branches - nothing is committed directly to master, qa/ or stable/ branches
  • Development branches should follow the naming format: dev/issue-####-short-description
    • dev/ marks it as being a development branch, not for QA integration or a stable release
    • issue-#### is the Redmine ticket that the work is mostly related to. If the branch expands in scope to include multiple tickets later, that's fine, and don't worry about renaming branches
    • short-description is a couple word description of the branch, to make it easier to remember what the topic of the branch is.
    • Example: dev/issue-8161-dashboard-i18n or dev/issue-8693-dataverse
  • Development branches should generally be create from the branch they will be merged into. In most cases, this is master, qa/1.x (Archivematica) or qa/0.x (Storage Service). If something is a patch for an old release, it may be more appropriate to branch from the old stable branch (e.g. stable/1.5.x)
  • All branches should undergo code review before being merged into the target branch. If something was developed for an old release, it should be cherry-picked to the current development branch, and a comment with the commit hash should be left in the pull request for tracking.

Archivematica merge process

We use a rebase-based workflow, where branches are brought up to date with the latest stable by rebasing them. (This is compared to a merge-based workflow, where branches are merged, and conflicts resolved in the merge commit). This shows the process for merging development branch dev/test into target branch master. The target branch is usually master, qa/0.x or qa/1.x.

The instructions are formatted: (current branch) $ <command to run>

  1. Check your remote is set to be gitolite
    • $ git remote -v should show origin<repository-name>.git
    • Not all repositories have gitolite as the canonical repo - ask if you're unsure
  2. Ensure your copy of the target branch is up to date
    • $ git checkout master
    • (master) $ git pull --rebase
  3. Ensure your development branch is based off the latest target branch
    • $ git checkout dev/test
    • (dev/test) $ git rebase master
  4. Check that your changes still work after rebasing
  5. Check tests pass (see for more details)
    • (dev/test) $ py.test
  6. Push your newly-rebased branch to remote. Because this is a rebase, which changes history, you'll need --force. The rebased dev branch has to be pushed before the master branch is or github gets confused.
    • Never force push on a stable/, qa/ or master branch!
    • (dev/test) $ git push -f
  7. Fast-forward merge
    • $ git checkout master
    • (master) $ git merge dev/test
  8. Push merge!
    • (master) $ git push
  9. Delete dev branch
    • Locally: (master) $ git branch -d dev/test
    • Remote: (master) $ git push origin --delete dev/test
  10. Update the related ticket, if needed
  11. You're done!

Proposed changes


  • Current status: All development branches are created in the artefactual (or artefactual-labs) owned repository, and core contributors (usually Artefactual employees) commit directly to the official repository
  • Proposed change: Development happens in contributor's forks, and the official repo contains only stable & QA branches
  • Pros:
    • Fewer branches in the official repository, so there is less clutter and noise for people watching activity
    • Handles more contributors, since there won't be dozens or hundreds of branches of uncertain development status
    • Contribution process is the same for external and internal contributors
    • Contributors can handle their repository branches however they want - naming conventions, deleting old branches or not, etc
  • Cons:
    • Potential confusion about which repository is the correct official one
    • Potential to push changes to the wrong repo (e.g. push a development branch to the official repo instead of the contributor's fork)
    • Developers have to keep 2 repositories up to date: upstream and their fork
    • Harder for analysts to check out development code, since they would have to set their remote to the contributor's fork

Hybrid merge/rebase model

  • Current status: All branches are rebased onto their target branch before being (fast-forward) merged
  • Proposed change: Small or minor branches are rebased, larger feature branches are true merged
  • Pros:
    • Commit history clearly shows 'feature', and which commits came in together as a unit
    • Rebasing small branches preserves clean history for minor changes
    • Better reflects nature of development - shows minor changes as happening inline, and major changes as happening in parallel
    • Merge commits are clear places to look for integration issues
  • Cons:
    • Confusion about when to merged vs rebase
    • Developers have to learn two workflows