Github is an online repository(repo) where programmers - which we believe is anyone who writes code - place their code. Programmers can then easily share their code with the world, and allow other programmers to take their code and adapt it. It is an example of the open source software movement, which is software in which the source code is freely available for others to view, amend, and adaptSOURCE.
At DfE's Coffee and Coding, we are moving to host non-Official Sensitive materials on Github. To help programmers upload their materials to our repo, we have prepared this how-to guide on how you can contribute to our repo.
- Creating a Github account
- Turning 2FA on
- Creating a PAT
- Cloning this repo
- Pushing your changes to the repo
- Uploading html, word, excel, or powerpoint files? Read this
Go to the Github homepage, and click on Sign up. Then enter your details.
When creating your password, use a password manager like Bitwarden or KeePass to make it. These create and hold all the passwords of your web accounts in one, safe, encrypted place. This will also be useful when you turn 2FA on.
Now that you have created your Github account, turn on 2 factor authentication (2FA). This creats an additional code which you enter - with your username and password - to access your Github account.
First, download an authenticator app on your smartphone, like OTP Auth, or Google Authenticator.
Then go to your secuity settings and click Enable two-factor authentication. You will be shown Recovery Codes in case you lose your 2FA app in the future. Save these in your chosen password manager. Click Next.
Then scan the barcode with your authenticator app, enter the 6 digit code shown on your app, and click Enable.
If you get stuck, just read this guide.
With 2FA set up, you now need to create a Personal Access Token(PAT) to send us files and folders.
To create, follow these steps:
- Go to Developer settings.
- Click Personal access tokens
- Click Generate new token
- Name it, select the repo option in scopes, and click Generate token
- Then save this PAT in a safe place, such as your password manager
If you get stuck, just follow this guide.
With our housekeeping tasks finished, let's move onto the interesting stuff. Namely, downloading (technically called cloning) the information in our repo to your machine.
This step assumes that you have Git installed on your machine. If you don't, a previous talk on using Git with your analysis work shows you how to install and configure it.
First, go to our repo's homepage, click Clone or download, and copy the url you see:
Now, open RStudio, click Project: (None), and then click New Project
then select Version Control
then Git.
Finally, paste the url into the Repository URL box
click Create Project... and wait. Hopefully with a nice cup of tea.
Once the cloning is finished, you should see the files on our Github repo in your RStudio Files pane
Now that you have downloaded/Cloned our repo onto your machine, you can contribute to it by adding files and folders to this repo, and sending an updated version back to us. We can then look at your updates and place them on our repo.
To do this, just add as many files as you want to your R project folder. Then when you have finished adding files, commit them in the Git pane.
After committing, you may see the message that Your branch is ahead of 'irigin/master'. This signifies that the commit history on your machine is different to the one on our Github repo. You want to see this, as it shows that you have added files on top of ours.
But now you want to let us know you have added these files, so we can then place them on our repo. To do that, you need to Push the differences by, well, pushing... the Push button on the Git pane.
Then wait, and when prompted, enter your Github username
wait a bit more, and then when you are prompted for your github password, enter the PTA you generated earlier. You enter this because we're using 2FA, where your PTA takes the place of your password when pushing content to us.
And if all that goes well, we will see the files you have contributed in the Pull requests pane, where we can approve them, or suggest changes.
Github was designed to host code. Hosting your python, R, sql, and markdown files on it thus hold no problem. Peculiarly, pdfs are also easily added.
But github - like git - hates non-binary files like rendered html, word, excel, powerpoint etc. Essentially, your files will be uploaded, but it will be very hard to view the raw code that creates those files on github. To make life easier for your viewers, place the url of your html or microsoft files into the box at DownGit, and place the Download Link you create in your README.md file. This will create a download link for the various html, word, excel, or powerpoint presentations that you would like to upload.