This is the lab's shared github space. We should upload any code and documents that could be useful for anyone in the lab to be able to use. See all open pull requests on Goffaux-Lab.
The guide assumes you already know how to make changes to a repository on your own account (i.e. the three stages: add, commit, push) - if you want a guide for that (plus a general overview) see here. There is also this website from which you can find anything git-related that you need (including the free online book Pro Git). There are also some slides that were presented in journal club to motivate the workflow described below.
Deleting your repository or changing its visibility affects that repository's forks.
On the Goffaux-Lab, private repositories can be seen and used by any member of the Goffaux-Lab, but not by anyone else. Public repositories can be seen and used by anyone in the world.
If you delete a private repository, then this will also delete all the private forks of this repository on others' accounts. To avoid this, you can first change a repository's visibility from private to public, and then delete it.
Github repositories don't allow a huge amount of data - so it's best not to upload a lot of stimuli (and definitely not experimental data!). For this, we should create a project on the Open Science Framework. You can link the OSF project back to the github repository that contains the associated code and upload the stimuli only to the OSF. In the README.md of the github repository, you can add a link to the OSF project.
In the following, the bold words are git specific terms which can be googled to learn more.
Github repositories can be forked between accounts (i.e. create a copy) so that others can use them too. The original copy is called the upstream. So you can fork a repository from your personal github account to the Goffaux-Lab account, or fork a repository from Goffaux-Lab account to yours.
On your personal github account you can make changes (or 'commits') to the repositories as you please. These commits can easily be synchronised back to the Goffaux-Lab account by doing fetch upstream or by submitting a pull request. See all open pull requests on Goffaux-Lab.
If you're working on a fork of a repository from Goffaux-Lab (i.e. you forked it to your personal account), and meanwhile someone makes commits to the repository on the Goffaux-Lab account (i.e. submits a pull request that is accepted), you can easily synchronise your fork of the repository with the updated Goffaux-Lab account (this is called fetch upstream).
Note: This will only work for your public repositories. To share a private repository with the lab, see below.
In order to make one of your personal public repositories appear on the Goffaux-Lab page, go to your public repository:
- Click the fork button.
- Make sure the Goffaux-Lab is selected as the destination.
- Click 'Create fork'.
Once the fork has completed, the repository will appear on the Goffaux-Lab page. Clicking on it we notice some things:
- It shows that the repository was originally forked from your personal account (the original repository is the upstream).
- We have the option to synchronise the fork by doing fetch upstream. This would copy over any new commits that have accumulated on the original repository since the fork.
Immediately after forking, there won't be any new commits.
If we make a commit (i.e. add some more code or fix a bug) in the upstream repository (i.e. on our personal account). Then come back to look at the fork on Goffaux-Lab, we see that:
- The repository knows that it is now 1 commit behind the upstream.
- We now have options available with fetching upstream.
- We can compare the differences between the fork and the upstream.
- Or we can immediately fetch those commits and merge them into the fork (i.e. synchronise the repositories).
Comparing the files looks like this:
Github will not allow us to fork private repositories. But we can transfer them over to the Goffaux-Lab account. This will mean that the repository will appear on the Goffaux-Lab's github account as the upstream and no longer appear on your personal account. To get a copy back on your personal account, just fork the repository. This is detailed in the next section.
In order to make one of your personal private repositories appear on the Goffaux-Lab page, go to the settings tab on your private repository:
Scroll down to the bottom of the page and do the following:
- Click on the 'transfer' button .
- Type 'Goffaux-Lab' as the place to transfer the repository to.
- Type whatever it tells you to confirm.
- Finalise the transfer.
If you want to use a repository that is on Goffaux-Lab, go to the repository and fork it to your personal account. You will probably want to clone the repository from your own account onto your local machine (unless you are following the steps from the last section, in which case you may already have a local clone). You are now free to make commits to your fork of the repository.
Once you've made some new commits to the fork on your personal account that make it better than the version that is on Goffaux-Lab, you might like to share it with the lab. To do this you must request that the commits on your personal account are synchronised back to the upstream on Goffaux-Lab. This is done with a pull request:
- From the repository on your personal account, click the 'contribute' button.
- Click 'open pull request'.
Doing the above takes you to a new page where you can prepare your pull requests. In this example:
- It says the name of the base repository that we are making our pull request to.
- It says the name of the head repository containing the new commits.
- It says if the new commits are able to be automatically merged into the base repository*.
- We click 'Create pull request'.
* If an automatic merge is not possible, it means that someone else has submitted a pull request with a commit that changes some part of the code that your pull request also changes. You can still make the pull request, it just means that the owner of the Goffaux-Lab who accepts/rejects the pull request would additionally have to decide which of the conflicting changes to incorporate.
We are then allowed to:
- Give the request a meaningful title.
- Add a longer description of what changes we have made.
- Finalise the request.
Later, the owner of Goffaux-Lab will review and accept the pull request. After this is done, the whole lab will have access to your changes.
This section is to be completed...
Once you've merged the changes into the Goffaux-Lab repository, you will see that this repository is now some number of commits ahead of your own (it can also be ahead, and behind at the same time - if you also made changes on your personal repository that are not on the Goffaux-Lab repository):
You probably want to incorporate these changes into your personal repository too. This is easy - click on the blue link in the image above, and you will be taken to make a pull request:
After clicking the button in the above image, you get to describe what the new changes are about:
Once the pull request has been made, you'll immediately be asked if you want to merge it with your personal repository (see Accepting others' changes (merge)).
