This workshop will involve a collaborative group exercise to build a 4IR webpage using GitHub, lead by Dr. Rachael Ainsworth, Research Associate in Radio Astronomy and Open Science Champion at Jodrell Bank Centre for Astrophysics, University of Manchester.
Agenda:
A brief tutorial inspired by the Mozilla Science Lab Friendly Intro to GitHub.
- Git is an open source program for tracking changes in text files. It was written by the author of the Linux operating system, and is the core technology that GitHub, the social and user interface, is built on top of.
- GitHub is a code hosting platform for version control and collaboration. It lets you and others work together on projects from anywhere.
- Open and reproducible science/code/research
- Open source software is software that can be freely used, modified, and shared (in both modified and unmodified form) by anyone. Today the concept of "open source" is often extended beyond software, to represent a philosophy of collaboration in which working materials are made available online for anyone to fork, modify, discuss, and contribute to.
- For more information on open source, specifically how to create and grow an open source project, GitHub have created Open Source Guides that will help you foster a healthy open source community.
- Project Management
- Websites
- Code documentation
- Open Educational Resources
- Open Data
- Online portfolio of your work
- All the things
Glossary via Mozilla Science Lab's GitHub Essentials
- repository, or repo - a collection of documents related to your project, in which you create and save new code or content.
- markdown - a lightweight way of annotating a document with instructions that tell a web browser how to format and display text.
- version control - a way of tracking changes to a document or collection of documents. Version control is like a time machine, it can take you back to the moment your document was created, or any other point in time when you or a collaborator saved that document.
- Git - the command-line software that tracks all changes to a collection of documents.
- GitHub - a service that hosts your repository online and helps you work with contributors. GitHub adds a web-based interface to version control.
- fork - a copy of a repository that is saved in another user's GitHub account.
- branch - a copy of a repo that is contained within the original repo. Branches are used to work on a project features without altering the original or "master" repo.
- commit - a saved change to a document in a repository.
- issue - a message on GitHub that outlines a task that needs to be completed.
- pull request - a request to add a commit or collection of commits to a repository.
- merge - the act of incorporating new changes (commits) into a repository.
- README - a document that introduces an open project to the public and any potential contributors; the first thing you see in a repo; usually written in Markdown
Markdown is a lightweight and easy-to-use syntax for styling your writing. It includes conventions for
Syntax highlighted code block
# Header 1
## Header 2
### Header 3
- Bulleted
- List
1. Numbered
2. List
**Bold** and _Italic_ and `Code` text
[Link](url) and For more details see GitHub Flavored Markdown, Markdown cheat sheet and Emoji cheat sheet.
We will begin by following the GitHub Guides Hello-World tutorial where everyone will create a repository and edit the README to become more familiar with the GitHub platform.
There will then be a collaborative group exercise to build a 4IR webpage using GitHub!
- Identify what information/sections/tabs/pages you want to include on the website (e.g. an About page, an events page, a list of students/projects, a blog, contact info, etc.).
- Choose a theme (e.g. from http://jekyllthemes.org/) that will best present that information.
- Go to your chosen theme's GitHub repository (e.g. Project Pages used in our example here).
- Fork the theme repository. This makes your own version of the content that you can edit and use while maintaining credit to the theme authors.
- Go to Settings to update the repository name (e.g. to
username.github.io) and enable GitHub Pages by selecting a branch (e.g.masterorgh-pages) as a source for your webpage. - Edit the
_config.ymlfile to point to your repository, change the title and any other user information. - Edit the
READMEto include information about the website or project repository (read more aboutREADMEfiles here). - Make your changes! In this case, add or change elements to the website as you see fit (e.g. add relevant information to the About page, add an events page with upcoming 4IR CDT workshops, create student profiles). For this workshop, we will make our changes in the GitHub interface. Once you're happy with your changes...
- Submit a pull request. This opens a discussion around your project and lets the project lead know you are proposing changes.
- Merge the pull request and check out your website! 🎉
Is there still time left in the workshop? Try making a website for your personal GitHub account following these steps! We can link them to the student bios on the 4IR CDT website. 😎
- GitHub Guides - https://guides.github.com/
- GitHub Glossary https://help.github.com/articles/github-glossary/
- Understanding the GitHub flow - https://guides.github.com/introduction/flow/
- Mastering Markdown - https://guides.github.com/features/mastering-markdown/
- How to choose a license for your GitHub repository - https://choosealicense.com/
- Mozilla Science Lab GitHub Essentials - http://joeyklee.github.io/friendly-github-intro/guides/github-essentials/
During the workshop, the students identified the following to include on the website:
- Events
- About page
- Vacancies
- Project partners
- Student profiles
- per year?
And voted to use the Sleek theme.