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).

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.

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 <them>-<branch_name> <them>/<branch_name>