GitHub for Code Management

Our small multi-developer teams have a critical need to manage the code bases that they work on for each project. We use a distributed version control system (DVCS) for this purpose, which brings about the proper workflows and creates a cohesive development process. For our work with CFPB, we have used Git and Github.

Git is a free, open-source software, installed locally and manipulated through command-line interface, that tracks revisions to a developer's code. Individual revisions are saved as a commit and the commit history is available for developers to compare to previous versions or rollback changes. This version control is crucial in enabling multiple developers to work together on a single project. By using Git, those working on a project can feel comfortable that new work will not be merged into the master copy of the work until it has been properly vetted. This process is fast and ensures data integrity.

GitHub is a cloud-based Git version control repository hosting service for Git. It provides all of the distributed version control and source code management (SCM) functionalities of Git and adds some additional features that makes collaborating on a project easier. The GitHub additional functionality that is essential to our distributed teams are the following:

• Fork: We have made a fork (a copy) of the CFPB central cfgov-refresh repository onto the Raft server so that we can develop the Money Tools and test them internally without any compromise to the CFPB master copy of the software.
• Pull: We take advantage of this feature internally when we want to merge new code into our primary branch as well as when we want to merge our finished code into the CFPB central cfgov-refresh master.
• Merge: Once any changes are properly evaluated, they are merged into the primary branch on the Raft fork. Then, upon final approval of our code, our primary branch will be merged into the CFPB central cfgov-refresh master. This merging happens with just a click of a button.

Our GitHub flow

Create a Branch

Branching is a core concept in Git and where our workflow begins. We create a new branch off the primary development branch,My-Money-Calendar in order to develop new features or evaluate any new ideas. Changes made on these branches will not affect the primary development branch so the developer may experiment and commit changes without concern. Your branch will not be merged until further down the development workflow.

Add Commits

Developers at Raft are encouraged to commit often and only commit changes that they have, themselves, completed. Each commit creates a rollback position in the codebase. Also, team members are asked to include explanatory messages on each commit. The list of messages from these commits can be critical to reconstructing the thought process of the developer.

Open a Pull Request

A Pull Request (PR) initiates a conversation about the associated commits. We use a standardized template that developers complete when submitting a PR. Any other supporting information and screenshots are included also. In general, we expect every PR to follow this pattern:

• This pull request changes...
  • The first expected change is...
  • The second expected change is..
• This pull request is ready to merge when...
  • Tests have been updated (and all tests are passing).
  • This code has been reviewed by someone other than the original author.
  • The experience passes a basic manual accessibility audit (keyboard nav, screenreader, text scaling) OR an exemption is documented.
  • The change has been documented.
  • Associated OpenAPI documentation has been updated.
  • Changelog is updated as appropriate.
• This feature is done when... - Design has approved the experience. - Product has approved the experience.

Discuss and Review Your Code

The discussion thread on the Pull Request is a conversation between the developer and the reviewer(s). There may be questions about the functionality of the code. It is also an opportunity to make sure that the new code adheres to CFPB style, content and accessibility guidelines. Often the conversation will consists of back and forth until the reviewer is satisfied that all criteria is met and approves the PR. The new code is, then, ready to be merged into the main feature branch.

Deploy

We start by deploying to a staging server to make sure that the code will can successfully pass through our testing pipeline before we PR to the CFPB master.

Merge

Once the code passes the review process, it is merged. The merge process preserves a record of the historical changes to your code and is searchable. The value of this is that a future member of the team can go back and understand the changes and the rationale involved.