GitHub repositories practical

User security

You can make organisations (which are basically groups that own projects rather than individual users).

This is a matter of choice (or lab policy) but I generally release work projects under my organisation as it’s more professional, makes it easier for my coworkers to maintain it, and our lab seems more permanent than an individual job. You can always transfer it, and have the old URL redirect, but generally it’s better to make URLs permanent.

Access tokens

GitHub uses Personal access tokens rather than passwords. To generate one of these for the VM:

Click on your user icon in the top right
Click “Settings”
In bottom left menu option - “Developer Settings”, then “Personal Access token”
Generate new token, label it something like “bioinformatics VM”. Make sure you click the first tickbox “repo” so you can use it to push/pull

DO NOT CLOSE THIS TAB - leave it open so you can copy/paste it below

You can store your token (as plaintext on the VM) via:

git config --global credential.helper store

If you do this you will only have to enter your token once. If someone gets this token they can make changes to your GitHub repo so please password protect your VMs

When it comes time to enter git username/passwords - you do NOT enter your github password, you use this token.

New GitHub project

On https://github.com - create a new project:

In the top right hand corner, click the plus symbol, then “new repository”
Call it eg ‘github_practical_example_project’
Choose a licence (any will do), add a README.
Make it public (you can always make it private later, or delete it) - you need it to be public to be able to use the wiki

Clone your repo

Go to your project on GitHub
Press the green “Code” button in the mid-top-right - this should open a “clone” window
Copy / paste the URL, it should be something like “https://github.com/YOUR_USERNAME_HERE/github_practical_example_project”
Clone it to your VM:

git clone https://github.com/YOUR_USERNAME_HERE/github_practical_example_project

If your repo is private, you will need to enter your username/password here. The password is the access token (not GitHub password)
Make a change to the README.md

cd github_practical_example_project  # go into the repository you just cloned
git add README.md
git commit --message "edit README"
git push

If the repo is public (and you didn’t have to enter it when you cloned it - as anyone can do that) you will have to enter your github username and password now. The password is the access token (not GitHub password) in the tab that we told you not to close.

If you did close the tab, just create another token now, and use that.

Issues - searching

Go to IGV issues

Notice how all you can see are the titles. Titles are extremely important.

Before raising a bug, you should always check it see if it has already been reported (ie don’t create a “dupe”)

Run a few searches. Experiment with clicking on Open/Closed. Notice how special tokens in the search form change.

Again, notice how the title is critical for finding things as you can’t see the contents (though you can search for it, eg “font” will bring up titles without “font” in it, as they have it in the issue)

Issues - labels

As well as titles, labels can be used to organise issues into related themes. Read the documentation Github - managing labels

Create some labels for your project, with distinct colours - if you’re unimaginative you could use “red”, “green”, “blue” with appropriate colours
Raise some fake issues on your project, don’t worry about content just make a lot of different titles (ie “problem X with red”, “problem Y with red”, “problem X with green”, “problem Y with green”)
Tag the issues with appropriate keywords (view each individual issue, click label cog on right hand toolbar, select from autocomplete)
Perform a search for keywords, and notice how the labels make it easier to find related
Try clicking on a label (this does a search by label)

Issues - lifecycle

Issues move througha lifecycle, ie:

raised -> fixed -> tested -> closed raised -> tagged as “duplicate”, “wontfix” -> comment about which other issue is a duplicate + close

Find an issue,
Add “wontfix” label
Add a comment at the bottom saying this issue is too hard / out of scope of the project and close the issue
Go back to the search, notice it’s gone

Issues - writing tips

Even for your own projects - try and write it with as much information as possible (aiming to be standalone, so you don’t need much outside context), so that a 3rd party can come in and make sense of things.

If it’s clear - maybe it’ll stop them raising a dupe. Maybe someone will fix it for you!

Depending on the type of bug, there’s certain information you want to include

For crashes: stack traces and logs

For ones that involve complicated user steps - Try to find a way to “reproduce” the error consistently and produce clear step by step instructions. Ideally your instructions should reproduce the issue 100% of the time with a minimal amount of steps

For ones involving input files, perhaps try and produce a minimal, cut down one.

For unexpected behavior, or outputs, Actual vs Expected is very useful

Milestones

Milestones are a way of managing releases and deadlines

For instance, you may have 20 issues, but your lab head says you have to stop coding and start writing up your paper in 2 weeks.

Create a milestone called “Code complete for paper” with a deadline in 2 weeks time
Assign a few issues to this (you will need to go into each individual issue, click milestone cog, select from autocomplete)
Go back to issues, search by milestone

Wiki

Note: Free GitHub accounts can only have wikis on public projects

Check to see if you have a “wiki” menu item on your project. If you don’t you can either skip this step or make your project public.

Go to settings
Scroll all the way down into the “danger zone”
In “Change repository visibility” set project to public
In settings again, you should now have an option to enable wikis

To experiment with wikis:

Create a few wiki pages for your practical project (the one you made not forked)
Use 2 levels of headers “#” and “##”
Go to the wiki page, notice that it has built a hierarchical wiki browser for you out of your headers
Try out the search and expanding the wiki in the right side of the screen

Simulated open source project repo

Practical - simulated open source repo

There’s a GitHub repository Practical project which is a simulation of an open source project with bugs.

It has randomly generated data, so has the same structure (but different data) as Assignment 5

File history

From the project page, click on “data” then click on your student number .txt file. You can see the latest content, and the last commit.

Click “history” in the top right hand corner to see all the commits.
Go back and click “blame” to see commits that last touched a row

Branches

Branches allow you to keep different versions of code (say, a “stable” vs “experimental/active development”) and keep work separate.

You can split off branches, and merge branches into each other.

Git - branches in a nutshell GitHub - about branches

Click on the “branches” links on the practical repo

Raising an issue

Raise an issue in the GitHub repository Practical project for the high severity bug (XXXXXXX)

Make sure the title includes your filename and what’s wrong with it, ie “file doc/a1059391.txt contains ‘XXXXXXX’”

Remember to be nice - perhaps start the issue with “Hi, thanks for your project! I think I may have found an issue” - be humble and kind. You may be adding more stress to an overworked person trying to do altruistic work…

A bad issue raises stress but a good issue helps people, and makes it more easy for them to fix, and happier to do so.

Write Actual vs Expected for your file, only mentioning the high severity bug (XXXXXXX)

Fork the repository to your personal account.

You can now clone your private fork of the repo to your local machine.

Fix the high severity issue (XXXXXXX)

Edit your data/ file, and remove the high severity issue (XXXXXXX) ONLY (ie DO NOT change the low severity (UPPERCASE) at the same time). There should only be 1 space between the words after removing the XXXXX
git add then git commit --message "fix issue #xxx" (referencing the issue in the original repo you raised)
git push back to your repo

Your forked repo

Go to your forked repo page.

Notice your files last updates have changed
Notice it says “X commits ahead of the old repo”

Submit a pull request

Create a pull request from the front page of your repo (near “X commits ahead”)
Comments should link to both issues and give a brief description of the change. You don’t need to repeat everything in the issue, just link to it
after creating the pull request you’ll be taken to the original repo (not your fork) - notice that the “pull request” tab now shows some numbers. Notice how the pull request comment can be hovered over to see the issue
Go to your issue - you should be able to see the linked pull request

Extras

Try editing the README on GitHub as well as locally. Try editing different lines then push/pulling. Try editing the same line then push/pulling
Tags are a label for a commit, and are useful for things like “tagging a release”. It’s easier than memorising a date or a hash. Try making some tags for your repository. Google for help on GitHub tags to find out the steps
Read some closed issues on some famous bioinformatics GitHub projects, eg: IGV, Samtools, BWA Notice how they often involve conversations over long periods of time.