GitHub for Devs & Workflows

This is the fifth and final post in a multi-part series on using GitHub for Government. In the previous posts in this series, we've discussed the basics of GitHub for Government, what the public can and can't see, what code should and should not be included in a public repo, and GitHub users and permissions. Now let's dive into developers and workflows.

An overview: How are things organized on GitHub and who does what?
GitHub organizes projects by associating them with an organization. We'll use Agency Z as an example. Agency Z has 10 projects on GitHub. The authoritative versions of these projects is the Agency Z copy of the code. A select group of developers has administrative access to this code, but the vast majority of users -- interns, junior developers, consultants --- have read-only access. If one of those read-only users wants to make changes to a project - say a summer intern wants to propose a new widget, they will fork the code of a particular project to their account, which essentially creates a copy of the code in their account for editing. This won't give that summer intern access to the company's original code, but it will give them a copy of the code to play around with.

When they've made the changes that they desire -- in this case to implement a new widget -- they can send those proposed edits back to the agency as a pull request. This pull request will become visible to all members of that intern's team, and each of those users can review the changes. If more changes are needed, a user can send it back for development, but if they like the changes, they can accept them by clicking the Agree button, which will merge the pull request with the authoritative version of the code.

Anyone with read-only access can review changes, but only people with administrative permissions can actually accept the changes. In this case, other interns or junior developers could review the new widget, and leave comments like this widget works as expected, but only administrators could click ‘Merge' and ‘Accept' to make it a part of the authoritative version of the project.'

Is there a way to ensure no code gets in without peer review?
The simple answer is yes. As described above, there is a review process dictated by permission levels. So if your organization is very conservative about your permissions, you give almost everyone read-only access, and only a very small number of people administrative access. That way, there is a large pool of users to review the work, but only a select few administrators and gatekeepers that can merge and accept pull requests.

It's also highly effective to have a rule in place that doesn't allow developers to merge their own code. I've seen regression rates drop to nearly zero by enforcing a workflow like this. Whether it's actually enforced with permissions, or it's just enforced by having an organizational policy that says, No developer is allow to merge their own code. Everyone has to get peer reviewed and merge through a pull request.

How does a GitHub user go about submitting changes?
In order to make changes to a project, a user will need to clone the project, which creates a copy of the project in their own user profile. Within the copied repository, there will be a few simple project files. The user will want to open the READ.ME file in a text editor, change the cde that they desire, and then save it. Once changes have been saved to the local copy within the user's profile, they can submit a pull request with the proposed changes to other team members for peer review. For more in-depth, step-by-step instructions for the change and review process, check out this blog post.

What do you do when a user spots a problem, or something needs to be fixed before a change is accepted?
Let's say I've submitted a pull request with my proposed changes, and it's currently being peer-reviewed. Then, I find an issue that needs to be addressed immediately, but my changes haven't yet been accepted and merged. GitHub users can leave comments on a pull request as a whole, but they can also leave very specific comments line by line in the code when they're doing a peer review, and if they want to they can leave comments with check boxes. That way, a user could say Here's a list of issues that this code needs resolved before that step is committed, and then you can leave it for someone to actually work through those issues. A user can leave the pull request open, and can push more revisions up. Users can make it so that these conversations must be reviewed before the changes can actually be accepted.

How do developers get started?
I wrote a previous post on Getting Started: Collaborative development with Git, and that's a great starting point. It will walk you through a real life example, with graphical support. Start there, and you're well on your way to mastering GitHub for Government.