So you've been using some cool Python module and found yourself wanting to add some functionality that you've made in an ad hoc way in your notebooks. This tutorial will walk you through how to 1) get the official repository, 2) add your code, 3) create a merge request letting the maintainer know that your code is ready to be merged in and available for all to use.
Make sure you have git installed. You can check to see if it is installed by typing which git at the command line. If you don't have it installed, you can use sudo apt-get install git (Linux) or brew install git (macOS) to get a copy of this free software (if you are using macOS and you don't have Homebrew, definitely get it).
Once you have Git installed, you need to link up to the Git server (in our case, GitLab). Why? You need a way to authenticate each Git action (for example, copying or changing files). The best way to do this is using SSH keys. On the computer you are using to connect, generate a new RSA key with this command
ssh-keygen -t rsa -b 4096 # for macOS
and press Enter through the prompts (using the default "empty passphrase" setting allows you to make changes without typing a password, which is very convenient). The command creates two files in the directory ~/.ssh/. One, the private key file, is called id_rsa. Never give this out. The other, the public key, is called id_rsa.pub (full path: ~/.ssh/id_rsa.pub). You provide the public key to the machine you're connecting to. Interested in how RSA crypography works?. Copy the public half of your new RSA key to the clipboard with cat ~/.ssh/id_rsa.pub | pbcopy (macOS) or cat ~/.ssh/id_rsa.pub | xclip (GNU/Linux) and add it to the list of RSA keys on your GitLab profile. Done? Whew. Have yourself a beverage.
Remember how we were contributing to a project? The next thing we will do is create a local copy of the community repository. To do this, find the project on GitLab and copy the project's Git URL (it's in the box right in the middle under the repository name).
On the command line, change into your ~/Documents directory, or wherever you would like to keep the source code for this repository (I usually use ~/software on GNU/Linux). Then, use git to clone the repo and change into it. In this example, we will be cloning Tinkertoys (software for Design), but you'll substitute your own project.
cd ~/Documents # or maybe cd ~/software, or whereever you would like to keep the source code
git clone [email protected]:joshua/tinkertoys.git
cd tinkertoys Got the repo? Before we add any changes, we need to create a Git branch to keep track of the changes we make.
When you create a branch, you should include your user name in the branch name so it's easy to see who's doing what. For example, if you were creating a branch to fix a bug in encoding and your name is Rosalind, you might call your branch rosalind-fix-encoding. Of course, it's always worth asking the repo maintainer if there is a preferred style for branch naming.
In this case, I will be using rosalind as the developer user name, and fix-encoding as the description of the branch, but you should substitute the user name rosalind and the description fix-encoding for your own user name and description from here on out.
To create a new branch to hold your work before it's merged into the master branch, you can run
git checkout -b rosalind-fix-encodinggit will respond with this message: Switched to a new branch 'rosalind-fix-encoding'
In this case, we'll put the code we would like to add in a new file called fast_encode.py (full path: tinkertoys/sequence/fast_encode.py).
Now, we would like git to become aware of this new file. To do this, we can use git add.
git add sequence/fast_encode.pyA good check at this point is to run git status. You should see git recognize your new file as such:
On branch rosalind-fix-encoding
Changes to be committed:
(use "git reset HEAD <file>..." to unstage)
new file: sequence/fast_encode.pyNow that we have added the file. Let us commit it. To do this, you have two options, you can type git commit, and git will bring up your editor of choice. Or, you can do this in one line with the following command
git commit -m "Add my fast encoding algorithm" As a matter of style, Git commits should be phrased in the present tense and should answer the question "what does this commit do?" (as opposed to answering "what has this commit done?"). Try to phrase it as what the commit does rather than what you did to make the commit. In general, prefer "Add my algorithm" to "Added my algorithm".
Now that we have copied our code in and added it to git, we can push our results back up to GitLab so that the community can see them.
git pushIf you see an error message, git will provide you with the command to resolve it. In my case, I had to set my upstream branch explicity (this is for newer versions of git) using this command:
git push --set-upstream origin rosalind-fix-encodingThis part is a lot shorter. Find your branch on https://git.ginkgobioworks.com/ and click the "Create merge request" button (green).