Merging

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 git@git.artefactual.com:<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 https://wiki.archivematica.org/Getting_started#Tests 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

Forks

• 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