Skip to content

How to use GitHub Issues and Branches

We use GitHub to record the entirety of the scientific process: From hypothesis generation, discussions, experimental protocols and observations, data annotation and storage (as raw data or symbolic links), to data visualization and interpretation. Below is a step-by-step guide to a typical experiment workflow.

1. Open a Github issue for each experiment

Use Github Issues as the start and end points of your experiments (either wet- or dry-lab).

  1. To start an experiment, open a new issue on the respective project repository.
  2. Choose one of the issue templates (experiment, analysis, cloning, etc.) or a blank issue.
  3. Fill out the title, background and strategy sections of the issue body.
    • background: Describe what led you to do this experiment. Your description should be understandable without reading further background. Link to issues containing previous experiments (#<issue-number>), analyses and external citations that will help someone who wants to dig into the details.
    • strategy: Outline the experimental strategy in plain and understandable full sentences.
  4. Customize the tags and labels on the right panel:
    • Assignees: who will participate in this experiment?
    • Labels: use labels that will allow you to easily filter and manage your issues. Labels typically indicate what type of experiment it is (analysis, idea...) and the status of the experiment (to do, successful...).
    • Projects: selecting project board automatically links the issue to your project board, which allows you to easily track all your open issues.
    • Milestone: (optional) this allows you group issues by a common theme. Milestones might be helpful if you are at the stage where you are pursuing multiple different directions in your project.

Once you have completed the information above, click Submit new issue. The next step is to set up your issue branch.

2. Create issue branch for recording your work

The ability to have a branch for each specific issue is one of the main reasons we use GitHub as your lab notebook. Branches allow you to isolate your work on an experiment without affecting the central copy of your lab notebook, i.e the main or master branch of your project repository. This is a key feature if you are working in a collaborative experiment where each person needs to update their notes and protocols without interfering with each others work. Moreover, branches allow you to work on multiple experiments (issues) at once, while being able to keep your commit history linear for each of your experiments.

The easiest way to checkout and manage your issue branches is as follows:

  1. Download the Github Issues & Pull Requests on vscode marketplace
  2. Open your project repository on vscode (make sure you are logged into GitHub)
  3. Click on the GitHub icon the extensions bar, and hover over the issue you want to start working on.
    • Click on the arrow start working on Issue and Checkout topic branch

3. Save your progress as commits

Now you can start working on your experiment and analyses. Remember to switch branches following the same steps whenever you want to work on different issues/branches.
Record your experimental protocols in a markdown document in the experiments\user folder. As you plan, record notes and observations, and add new files, save your progress as commits. Git/GitHub allows you save snapshots of your work as commits. Here is an example. To learn how to use version control with vscode, see here. Writing succinct but descriptive commit messages will help you find changes easily. These are some pointers on how to write good commit messages. Commits should always be linked to specific issues. You can automatically ping issue timelines with a commit by including the issue number in the issue title body.

4. Use issue comments to discuss troubleshooting and results with collaborators

As you perform your experiment, you will often want to discuss your progress and intermediate results with your collaborators on the project. Use the comment section below the top body of the issue to post figures, links to code commits, and tables. Issue comments will capture changes in experiment design or interpretation of results. You can link to issue comments from other issues or repositories.

5. Wrap up experiment with pull requests

  1. Update the issue body to include the main results of your experiment or analysis.
  2. Update any links to experiment protocols and analyses in the issue body.
  3. Add a Brief Conclusion, in which you link the next steps/issues, if any.
  4. Now you can merge the your issue branch with the main branch by creating a pull request:
    • Go to the GitHub extension on you local vscode
    • Checkout the issue branch you want to merge
    • Hover over the Pull Requests top tab and click on Create Pull Requests
    • If there are no conflicts, you can Merge pull request. Choose the option Create a Merge Commit.
  5. Go back to your issue on GitHub, and link your pull request on Development.
  6. Update issue labels.
  7. Close issue.