GitHub Guidelines For Collaborative Coding

At Runtime Verification, we want to be as efficient as possible with our software development, but working on a team necessarily introduces inefficiency, which companies must manage. Being remote-first also presents unique challenges that teams must actively and intentionally overcome.

An example of why efficiency matters: suppose you have a six-week engagement with a team of two (12 person-weeks), and there are three separate half-day delays per week (seems small, right?). Then you have a minimum of 9 days delay (1.8 weeks, 15%). Delivery could have happened roughly a week earlier. Likely these delays even trigger other delays compounding the issue (delay in one timezone causes blocked work in another timezone?).

These guidelines are ones that RV uses to manage group coding and may help your team avoid introducing unneeded friction into the group coding process. They are guidelines, which means one should strive to follow them but understand that real life is often unpredictable. Therefore such procedures may need to be adjusted to accommodate the situation.

In the ideal development scenario, everyone would be merging at least one pull request (PR) daily for each project they are working on so everyone is working with the most up-to-date code possible. Merging a PR requires three main steps: (i) write code, (ii) pass CI, and (iii) pass review. Each part of this process takes time, and step (iii) requires synchronization with someone else. The overall process is just beginning when you are writing the code.

The best way to ensure low friction is to open small “obviously correct” PRs. In the smoothest scenario, you open a PR that is small and focused and makes an improvement. The reviewer can quickly tell it’s a good thing and approve/merge it before asking you for more feedback. In this scenario, the burden of creating “easy-to-merge” PRs is on the PR author. When the PR author does not make “easy-to-review” PRs, several things happen: (i) the change description cannot adequately describe the change set, thus we lose track of what changes are made, (ii) review quality goes down drastically, and (iii) the PR stalls out in the review for a while (meanwhile the code is changing, which leads to merge conflicts, and other team members are not getting any benefit from the PR yet).

Prioritizing Work:

Ideally, the developer would handle the to-do list in this order:

  1. Review any PRs asking for your review and passing CI, or coordinate with other reviewers to assign it to them. Failing to ensure that PRs are being reviewed as requested also blocks the PR author.

When following these steps, the time zones of the people you work with should be considered. If you have 2 PRs open that you need to review or that you need to fix, (a) one for someone who is working now and will go offline soon, and (b) one for someone who is not yet online anyway, prioritize working on PR (a) over PR (b) in your queue.

Opening PRs:

  • Make small, focused PRs that address precisely the problem that is needed.

Reviewing PRs:

  • It is best not to spend much time reviewing PRs failing CI (unless you have been asked to provide early, quick feedback, which is good practice if you are new to a project). Just ask the PR author to get it to the point where it passes CI before requesting a review.

Addressing Changes:

  • For each requested change, you should take one or more of the following actions depending on the scenario, and always make sure you indicate that you have seen and handled the comment in the GitHub interface:
    The requested change is unclear: ask for more clarification (if this happens via DM, summarize the conversation on GitHub).
    - The comment is just a question where they don’t understand the code, or they request a change that makes no sense: answer their question directly (DM OK, but make sure to summarize on GitHub) and consider adding a comment to the code so that others do not have the same confusion.
    - The requested change is small or necessary for the PR’s correctness: make the requested change, and respond with “Done” or “Fixed” on GitHub to let them know you saw the conversation.
    - The requested change is large, would be scope creep, and is not necessary for the correctness of this PR: make a new issue for the requested change (or find an existing issue), and link to it on the comment.

Closing Remarks

This post does not discuss how to actually write code, just how to collaborate with others via GitHub when writing code. At RV, we try not to enforce any particular development style on people on their machines: we encourage teammates to use the IDE they want and manage their git history how they want. We only try to enforce basic sanity on GitHub (squash merges only for linear history, require branches to be up to date, etc.). One true thing is that you should know your tools no matter what technique you use to program. Take time to understand Git, IDE, testing tools, CI scripts, etc., to be an effective developer. Chances are, if you have some confusion or general pain point when doing development, the others on your team have already found a way to solve that problem! If not, then the team should discuss and address it.

A good read about developing code (short, <2 minutes) is “Simple, correct, fast: in that order” by Drew DeVault. In brief, at RV, we focus on producing code that is: “correct; (simple | fast); complete: in that order.” Note that we differ from the above article in that correctness is prioritized (we are producing software for quality assurance, after all), and performance is prioritized to be balanced with simplicity (our software is compute-intensive, so performance is a deliverable). Completeness is added (the idea of “handling all cases”). Following this philosophy when making and reviewing PRs has led to more maintainable code.

This post does not cover the use of CI (continuous integration) in aiding collaborative coding. Perhaps aiding is too weak a word here; fast, smooth, and ubiquitous CI is essential when developing in a collaborative setting. There are few worse things than pulling in someone else’s changes and suddenly having your local checkout stop working because of breakage introduced by them. At Runtime Verification, we have an extensive and thorough CI infrastructure and emphasize automating as much of the development process as possible. Our projects are complex and span dozens of repos, with internal dependency chains up to 6 or 7 repos deep in some cases. As much as possible, we test changes downstream early and push updates downstream automatically so that all repos use the most recent version of upstream dependencies. Perhaps we will write a post describing our CI setup in the future.

In conclusion, there are many ways teams might work together to improve productivity and efficiency when working remotely in a team environment. These strategies may only work sometimes, and they may only work for some teams. We hope that by sharing the approach that the developers at Runtime Verification use for code development, you might begin to implement and improve your own productive remote working environment.



Runtime Verification Inc. is a technology startup providing cutting edge formal verification tools and services for aerospace, automotive, and the blockchain.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Runtime Verification

Runtime Verification Inc. is a technology startup providing cutting edge formal verification tools and services for aerospace, automotive, and the blockchain.