Collaboration Workflows

There are many things you could do to make collaboration with other developers more convenient. This page documents some options and conventions.

Merging and Rebasing

Generally speaking, we rebase away from main, and merge towards main. For instance, feature branches (especially big ones) are typically rebased onto main to get the latest changes on main prior to merging them. This ensures that:

1. The feature branch will represent the proposed state of the main branch and any would-be issues would be noticed prior to the merge.
2. It avoids gratuitous complexity in the commit history (three-way merges, etc.) by ensuring that merging only happens in one direction (i.e. towards main).

Rebasing an Integration Branch

For a large integration branch, it's a good idea to periodically rebase it onto main to minimize conflicts and complexity on the final rebase. This should be done with care, as any in-flight PRs against the integration branch would then not be mergable (without their being rebased). To avoid these issues, these periodic rebases should be done at points when all in-flight work has been integrated into the branch, and collaborators should be notified prior to doing the rebase in case they have any WIP branches that they haven't publicly shared.

Rebasing a Stale Development Branch

For our purposes here, we'll use the term "development branch" to refer to a branch where you're working on a feature against an integration branch (not the main branch). In these cases, if the integration branch is rebased to main, you would not be able to merge your changes into the integration branch as the commits on your branch would not match the integration branch at all, preventing Git from seeing that your branch was originally based on the integration branch.

Ideally this situation should be avoided, by only rebasing the integration branch when there are no in-flight development branches. But if you do find yourself in this situation, then fear not! All you need to do is git rebase -i <integration-branch> (interactive rebase) and delete all commits that aren't specifically the ones you worked on in your development branch, and execute the rebase. That should go smoothly and you will then be in a position to merge your work, as you were before.

Git Remotes For Each Collaborator

In your local repo,

$ git remote add <them> [email protected]:<their_username>/qi.git

... where "them" is any convenient alias you'd like to use to refer to your new friend, the other developer.

Now you can always:

$ git fetch <them>

to try out their latest changes. If you want to make local changes or contribute to their branch, you could use:

$ git checkout -b <local_branch_name> <them>/<branch_name>