A Complete Guide to Setting Up and Working with a Git Forked Network
I have spoken often about the Assembla process that we have been working in and how well it works for us, but how can you get the same benefits for your project? Well, there is no secret, its just a matter of setting up a development fork and merge network. The basic idea is to isolate development work from stable work. By isolating, all development work from stable work you have a clear path from developer to production. Although this process is not specific to Assembla, lets see how this will would work utilizing Assembla. One could tailor this process to work in any system, and it would be just as powerful, though not as convenient as with the tools Assembla provides.
First we need to setup a new space. You can do this from your Assembla start page by clicking the 'Create New Space' button. Depending on your account and plan, you might want to setup a public or private space. It does not matter which type of space you setup.
Great, we now have a place to work within. We need to have a Git Tool, if your space configuration did not have a Git Tool, please add it from Admin tab and then the Tools Heading.
Whether you just created a tool, or it came pre-configured, I highly suggest renaming the Git Tool by going to the Setting subtab. Here you can rename the repository to “origin” and set an extension if you like, for the origin repo, I do not like adding an extension – I like the origin named “project.git”. I like calling it “origin” since this is standard git terminology for the original point of the code.
Now we have a Git Tool renamed to “origin” but no code in it. At this point, we can push code up to this remote repository and utilize it like we would normally utilize a git repo. Just to ensure everything is working, let's make sure we can read and write to the repo. Before you proceed ensure that you have added your public ssh key to your profile (found in the upper-right dropdown menu->Edit Profile->SSH Keys). Once your key is added, follow these instructions (replacing project.git with you appropriate project name) on your localhost to create a local repository that you will sync to the remote repository:
$ git clone git@git.assembla.com:project.git # will complain that you cloned
an empty repo
$ cd project
$ echo “Project Readme File” > Readme
$ git add Readme # add Readme file to git tracking
$ git commit -m “Initial commit of Readme file” Readme
$ git push origin master # create a master branch in “origin” repo
We have just made our first commit to origin/master. If you prefer you could use the http(s) method to interact with your git repo. Https is particularly useful behind a firewall that does not have port 22 open for ssh (many corporate firewalls are setup this way), while still encrypting your data. Http(s) will have more overhead and therefore slower than the ssh protocol. It does not update your localhost with information as often as the ssh protocol (sometimes it looks like it is hanging when it is working) because it waits between actions before responding to your client.
You can view this file that was just created in your code browser by navigating back to your Git Tool in Assembla and using the Browse Code subtab. To see the actual commit, take a look at the Commits subtab.
Hint: When committing add status updates such as fixed #123 or re #123 to reference the ticket in your commit message and to post a link and commit message on the ticket.
Theory: One could just work in the origin repository. You can branch and commit to origin like you would any other repository, however, this can cause bottlenecks and problems for your development process. Say that developerA commits bad code to origin/master – they discover this through QA, UAT or CI, and developerB needs to perform a critical hotfix to Production. If all are committing to origin/master and deploying this to Production, then we have a bottleneck caused by developerA's bad commit. This commit must be reverted or possibly you could branch before the commit add developerB's commit to this branch, then deploy out to Production this branch. Ugh, that is dirty.
Another model may use release branches to help solve this. Release branches rely on the fact that no-one alters them between releases but takes overhead to cut them, coordinate developers and manage them. This becomes very hard to maintain across many, many developers and does not allow a free-flow of code from developer to Production, instead you must commit to several branches to ensure that you keep your Development branches and Release branches in sync. Often release branches become divergent from Development branches and you cannot patch them easily as there are different codebases and the merge results in conflicts or there is logic missing that is expected.
Instead, we introduce the Developer Fork. The Developer Fork is a repository that is based on origin, but allows the developer to maintain their own repository including branches, tags and commits. It also has one other nice advantage that is a little hard to see at first, but if managed properly, you will not run into strange merge problems with new work – all new work is applied on top of branches that are consistent with your current work. In other words, you will not get any of those annoying, you must merge before you can push errors.
To create the developer fork, go to your origin's Git Tool and then the Fork Network subtab, from here you can choose to fork your project. It does not matter if you do it to another space or within the same space. The considerations made to whether you will fork in the same space or to another space have to do with whether this is a new project being branched, if the developers will work off the same list of tickets, and if you have creation permissions in the space to create this fork amongst many other considerations. For our purposes and the purposes of most teams working on the same list of tickets, it is best to keep this fork in the same space – so that you can reference the tickets in the commits easily.
Once you have forked the repository go to the new Git Tool and rename it and give it an extension that matches the name in the Settings subtab. This will make it easier to talk about and remember where you are pushing code or merging to/from. For our purposes we will call it “fork”.
Advanced: Anytime you clone a repo, you are in fact creating a fork. You can then push this cloned repository to any remote repository. You may also connect any existing repository to any remote allowing you to maintain several remote repositories in a forked network in one local repo, you do not need to create a new tool or new space. If you already have two Git Tools in your Assembla space, you can add a “fork” from one repository to the other repository. Branches in git do not have to have a common ancestor nor do they even have to be related to each other; you can store completely different information in the same repository in different branches for git. So taking our origin/master setup in our space and a new Git Tool called “fork” and with the “fork” extension, we can clone this repository and then push a fork from origin back up to it. There are at least two ways to do it, each with different advantages:
# Using “origin” repository as your remote origin for your local repository –
typical for people who have read/write to origin/master
$ git clone git@git.assembla.com:project.git # should have Readme file from before
$ cd project
$ git remote add project_fork git@git.assembla.com:project.fork.git # add remote
for “fork”
$ git push project_fork master # create a master branch in the “fork” repo
# Using your “fork” repository as your remote origin for your local repository –
typical for developer setup
$ git clone git@git.assembla.com:project.fork.git # will complain of cloning
an empty repo
$ cd project.fork
$ git remote add project_origin git@git.assembla.com:project.git # add remote for
“origin”
$ git checkout -b orig_master –track project_origin/master # switch to local
branch “orig_master” and track the origin/master remote repo
$ git push origin master # push the orig_master branch to the “fork” remote
(origin of this repo)
You can repeat the process above as many times as you like. I prefer to do this on a per developer basis. But you can easily setup a team that works in branches and has a common fork/master. This is the fork per team methodology. The advantage here is you have a single point of control for batching releases per team. However this same advantage is also a disadvantage where you have a bottleneck if a developer has committed code that is not clean or is waiting on other code.
Theory: The advantage of the fork per developer is that each developer is responsible for their own fork/master, and if they commit bad code or are waiting on other code, they do not block any other developer. This allows releases to occur more often on a per developer basis. If you are not in an environment that can sustain many releases very often, then you would arrange the fork network a little differently. Instead of developers working in the fork of origin, they will work in a fork of the fork – yes a fork of the fork. Just make the fork from the fork of origin, and you will have a repository that can merge easily back to the first level fork (use the fork network for this and just fork from the team fork to create a developers fork that will merge back into the team fork).
Theory: In general it is good to create a new branch for all isolated work, i.e. each ticket that you work on should be in its own branch. This allows a developer to start and stop work, or wait while work is reviewed or QA'ed, but still moving forward with other work.
When working on ticket branches, which I like to call ticket_X where X is the ticket number, are disposable branches. Assembla has created a convenient way of maintaining disposable branches, in your Git Tool Settings subtab, you will see a section that allows you to denote the pattern for naming disposable branches.
Then when you Merge or Ignore a Merge Request that is based on this branch, the branch is automatically deleted from the repository – truly helps with keeping a clean Development Fork. It is important to understand that even if a branch is deleted, no code is lost, that is the beauty of git, all commits are still present and the branch can be recovered if necessary. Typically, the developer will also have these branches locally still and can push them back up.
Theory: The general rule of merging is that you only want to merge from where you branched or to where you branched. If you jump across branches, the merging will work, but it might have seemingly strange results or may affect files that you did not mean to affect. So merge from your fork/branch to your fork/master and from your fork/master to your origin/master but not from your fork/branch to origin/master. That is a simplistic view – I am assuming that fork/branch is always coming from fork/master – but this does not have to be true. And moreover, it will not be true when hotfixes are done.
When merging from a fork upstream to your origin or from a 2nd level fork upstream to the 1st level fork (fork per team), you can create a Merge Request from the Submit Code tab, choosing your fork/branch as the Source (“From”) and the fork/master as your Target (“To”).
Theory: All code going into your fork/master should be Production-ready code. To ensure this, most teams will need a code review process. The Code Review process in Assembla can be accomplished in the Changeset view, which you can find from the Commits subtab where a reviewer can add comments directly in-line with the code, but more appropriate it can be done from the Merge Request subtab where you will submit a Merge Request from your branch to your master. You will choose your fork/ticket_X branch as the source and fork/master as your target. Then you will set a title and description and have the opportunity to review the new code that is potentially being merged to your fork/master. This is a good time to review that the code is as you expect it, this will prevent any gotchas later.
Hint: Add ticket status updates in your description with the same format that you can use when committing to your repo, i.e. fixed #123 or fixed #tickets to affect all associated tickets, to apply this status update once your Merge Request is Merged.
Once the Merge Request is created from your fork/branch to your fork/master you will have an interface where the team can have a discussion, including the ability to leave @mentions to alert others to help with code review, a list of the changesets that will be merged, diffs on the files that are changed, and a list of tickets (based on commit messages that include #ticket_num) that are being affected by this Merge Request, in-line code commenting, and of course a place to vote on the Merge Request. If you give it a -1 vote, the system does require you to submit a comment, this is because it is typically not beneficial to just leave a -1 without any comment – whereas a +1 speaks for itself (I highly suggest leaving comments on what is proper in the code with a +1).
Hint: Setup your CI server to automatically submit votes to your merge requests utilizing the API and/or JAMRb to run Jenkins builds off of your Merge Request. Authenticate with the Assembla Jenkins Auth Plugin.
If the Merge Request is merged via the “Merge and Close” button, the system will automatically merge to the target repository and the disposable branch will be deleted (if applicable). If Ignored, the disposable branch will be deleted and the Merge Request will be archived.
Deploys should always run from origin/master unless you are doing some creative deploying where you want to test out branches in Production before merging them into origin/master (this is a highly advanced workflow and typically needs a level of coordination and architecture that most projects do not have nor can sustain as they grow). This means that origin/master should always be deployable and developers can trust that if they fork/branch or merge from origin/master it has good, Production-ready code.
I mentioned that hotfixes are a bit different from regular merging workflow, well it can be true if you need to make a critical patch immediately. In this case its best to work from a branch of origin/master, even if you only have read access from origin/master this can be accomplished, since it is guaranteed to be in sync with your current Production if you always deploy origin/master. Once you have your fix in your local branch, you can push it up to your fork as a branch and create a Merge Request from fork/hotfix_X to origin/master; since you branched from origin/master you should merge directly back to it. To see how this would work in a developer fork with a remote of origin/master called orig_project and a local branch of orig_master tracking origin/master:
$ git checkout orig_master # checkout the origin/master tracking branch on a
remote called orig_project (not the origin of the local repository)
$ git pull # make sure it is up to date
$ git branch hotfix_ticketNum # create new branch locally
$ git push origin hotfix_ticketNum # push hotfix_ticketNum branch up to fork
remote (called origin locally)
Now you can create a Merge Request from fork/hotfix_ticketNum to origin/master and have Code Review before merging and then deploy to Production.
So that is basically how you set up a fork network in git for developers to be able to isolate their work and merge back to origin/master and from origin/master to their development fork.
To Learn more about other workflows, click here.