Tutorial: Contributing to the Student Resources List
Update 11/05/2022: The original list has been moved to https://github.com/Parentull/AwesomeResources. Please feel free to contribute to either list.
This tutorial is aimed at giving an overview of how to contribute to the Freeside Student Resource List on Github. I know, it's an oddly specific tutorial, but if you don't know, and are afraid to ask the question, then at least there's a handy guide (and I won't tell that you read the tutorial, promise!).
Of course, I do also have an agenda in writing this tutorial because I want to provide staff and students at the University of Hull with an overview of Freeside in general and spark interest in other projects we are working on, such as Hull Blogs - where we're aggregating blog posts by all Hull Students/Alumni, irrespective of area of study.
So with that said, let's take a moment to review what this 'Freeside' thing is all about...
Freeside is the University of Hull student run Linux Cluster. In essence, an unofficial 'society' based around Linux, System Administration and Open Source technology. It all started back in 1997, as can be read here. I'm also able to share an email from the 1990s(!), given by Prof. Brian Tompsett, about Freeside, parts of which have been redacted for privacy.
Subject: 08208 lecture
Message-Id: <redacted>
From: <redacted>
Date: Fri, 27 Feb 1998 01:09:16 +0000
Status: RO
Content-Length: 1090
Hi,
I have <redacted> to attend the
languages and compilers lecture, sorry.
On a different note, I don't know if you're aware or not, but the idea of setting up a unix cluster run by students has gone ahead. At the moment there's a rather out of date project page at
http://www.helios.demon.co.uk/freeside/
There's no 'proper' unix hardware there at the moment, just 4 VAXen.
A pair of VAXStation 3100's are running NetBSD/Vax via NFS from one of my PCs, and a poorly MicroVAX II (was Sarek.e-eng) that needs some attention.
Hopefully soon we'll be moving chekov.e-eng over to the 'Freeside' cluster, and a Sun 3/60 should be working again soon.
After talking to Prof Phillips last semester it seems that all we'll be able to let people do is have the machines as development platforms and filestores, I don't even know if a BBS [non-internet, non-dialup, 150.237.*access only] would be allowed, so if you have any good ideas or know of a source of inspiration, the project could do with a boost....
Thanks,
....<redacted>```Freeside is therefore the longest running Computer Science 'society' (official or not) within the Department of Computer Science & Engineering at Hull. It's also completely free to get involved and I would argue would enhance any students employability + earning potential enourmously given the demand for cyber security and linux administration skills.
So, why should you care? This is a tutorial about contributing to the Student Resources List. Get on with it already! Sure, sure... we'll get to that, but this is important.
Putting 24~ years worth of history aside, Freeside gives access to physical labs, opportunities to gain hands on experience maintaining systems for projects (like Minecraft servers and student run infrastructure!), an alumnus network like no other (especially if you're interested in getting advice from people working in a variety of roles across industry) and a wealth of knowledge about almost every CS related topic - though of course, mainly Linux, Open Source and SysAdmin; but it's not unusual to find debates about hardware projects, virtualisation, community projects, software implementation or anything else inbetween happening on the Freeside Discord or the Freeside Forum.
If all of that doesn't get your inner geek moist, perhaps consider the technology Freeside regularly utilises comprises the majority of web servers across the internet, runs ATMs, satellites, mobile phones (both Android and iOS are UNIX based) and everything in between - including NSA/GCHQ spying operations. Wouldn't you like to learn about the technology you use every single day, possibly without knowing?
You can join the Freeside Discord if you want to get involved immediately. Otherwise, finally, lets begin today's tutorial on Contributing to the Student Resources List.
What is the Student Resources List?
The Student Resources List is as described on the tin, a list of resources for Students; targetted at University of Hull students, but it may help students elsewhere. The primary aim is for students, whether part of Freeside or not, to contribute to it so the list is ever evolving and up to date.
When I started it, I thought of my progression from foundation to third year and how resources shared in group chats would eventually get lost or bookmarked and never heard of again; what was missing was a common reference point which everyone could easily access and update; hence the Freeside Student Resource List because it gives everyone the ability to build their confidence with version control methodologies, like git, whilst helping others in the process; you see, whilst it might just be 'one commit' or 'one link' to someone else, it is a really helpful resource that makes their day better and you, dear reader, are a life saver.
So, you may be wondering... how do you contribute? The process can seem a bit overwhelming at first, especially if you're completely new to version control, but don't worry. We've all been there!
Follow the steps below to make your first contribution:
Contributing
Step 1. Get a github account or sign in.
If you don't have a github account yet, you'll need to sign up.
Otherwise, go ahead and sign in.
Step 2. Browse to the Student Resources List.
Once you're logged in, head over to the Student Resources List. The link to the repo is, https://github.com/FreesideHull/StudentResources.
If you want to check out other repos in the Freeside Organisation, you can browse to https://github.com/FreesideHull. If you are a University of Hull student, you'll have the opportunity to join and manage these repositories.
Step 3. Star the Repo for easy access.
In the top right hand corner of the desktop version of Github, you'll see the star button on the repository. Click star. This isn't strictly a requirement, but it's good practice if you want to find the repository later.
Step 4. Fork the Repository
In the top right corner of the repository, you'll notice the 'fork' button. Clicking this button will create a copy of the Student Resources List on your profile. Generally, this will be available at github.com/YourUserName/StudentResources.
After forking, you will be able to edit your copy without changing the master copy available at https://github.com/FreesideHull/StudentResources.
Above we can see my forked copy of the Student Resources List. The red arrow points to the local forked repository, note that it shows the "StudentResources" next to my username and underneath the original repository.
The area above the yellow line indicates whether the repository is behind, even or ahead. If the repository is behind, this is because the original repository (in this case, FreesideHull/StudentResources) has had updates which are not incorporated to the local fork. If the repository is even, there are no updates to the original repository. Finally, if the repository is ahead, it is because changes had been made to the local forked version and if ready, we can make a pull request to add those changes to the original repository.
Step 5. Add some resources/Make changes
Here's where it gets a little tricky, because there are multiple ways to do this particular step. I'll list some of the ways below, before showing you how I personally make changes.
- Edit Directly on Github
- Edit using an IDE like Atom, Visual Studio, Visual Studio Code or Jetbrains
- Clone the repo using Github Desktop, Edit and then Sync the Changes
- Use the git CLI to clone the repo, make changes, and then sync the changes.
In terms of how I personally make changes, I use an IDE, at this point in time, Visual Studio or VS Code. This is all down to personal preference of course, but lets run through the process.
When opening visual studio, you'll be presented with these options. If you haven't already cloned the repo, you'll want to clone the repository from your github account. Otherwise, open it via a local folder.
Once cloned, you'll be presented with the following files:
These are markdown files. You can read more about how to edit markdown at Dev Docs but generally, if you are adding a new link the process is as simple as:
[LinkName](https://linktosomewhere.com)
Speaking of Markdown, we have a great resource listing some Markdown Editors that will be useful for learning more about Markdown, or just using a visual markdown editor. So lets add it to Programming.md.
The file has been opened and I've added the next number (12) to the list. The [] brackets will contain the name of the item and then we'll add the link. When it's completed, it should look like this:
If we view the changes using the 'git changes' view in Visual Studio, we can now see that the file has been changed.
Similarly, we can see which files have been modified in this view and write a message to tell others what we've done before committing and pushing the changes to the repository. Example as follows:
Following a successful push, we can see the updated files on our local repository:
We can also see some interesting information, the yellow line shows that the local branch, in this case, closebracket/StudentResources, is one commit ahead of the original student resources list hosted by Freeside. The red line shows the file that was edited along with the commit message and when it was edited.
So, how do we get our newly updated version merged with the original Student Resources List?
Step 6. Make a Pull Request
The answer lies in making a pull request. What this does is request that the maintainers of a particular repository 'pull' your updates into their version. You can read more about pull requests if you still aren't clear.
To make a pull request, click on Contribute and you will be presented with the following:
Then click "open pull request". After clicking, you'll be presented with a comparison screen which will try to detect whether your pull request can be merged or has errors/conflicts. In this case, the pull request can be merged and we can go ahead and create the pull request without much fanfare.
Click Create Pull Request and you will be presented with a form to fill in with a little bit more about your pull request. During this section, you could write more about the resources you've added, request a specific reviewer and attach files to support your pull request - particularly helpful if you're submitting extensive changes or about something very niche.
When you're satisfied with what you've written, press create pull request.
Next, you'll be presented with a similar screen. It's unlikely you will be able to merge the pull request directly as I can - I am the creator of the StudentResources list and a contributor, so I'm able to merge pull requests. In reality, it's more likely that you will endure a brief delay whilst someone reviews your pull request and either asks for changes, approves it or rejects it.
Step 7. A successful contribution
Given the example resource we've added in this tutorial doesn't pose much of a risk of breaking anything, we can approve it and call it a successful contribution.
Conclusion
This tutorial is by no means an in-depth tour of the capabilities of version control, and there are other ways to contribute to the Freeside Student Resources List, and other projects using git but the primary takeaway should be to follow the process and ensure your changes don't break anything before making a pull request.
Ideally, you would also be submitting high quality resources that would enhance others learning and understanding of computer science related topics, although personally, I have found that reading around other topics has shed light onto the flaws of technology as well. For instance, whilst I find it fun to reference NSA/GCHQ related spying projects because they are scary (and illegal), understanding the human element and social engineering provides perspective that technology comes with very human flaws, even if they are the users themselves.