GitHub is a cloud-based version control and collaboration platform based on Git. We're using GitHub to manage the source files for code, track updates, and facilitate collaborative editing.
This guide will contain some basic notes for MSE-Core contributors. There are excellent videos and guides on Git and GitHub that provide a more general introduction to these concepts.
A git repository is basically a folder directory with files. Git is the software that runs in the background, tracking the history of every change saved to the repository. You need to have Git installed on your computer and initialized in your directory in order to create a repository. Each contributor to MSE-CoreCourses will be working with two Git repositories.
- The Origin repository is on GitHub. This is where all versions of record for all of the files will be managed. All contributors have access to the origin repository.
- The Local repository is your copy of the origin repository that is stored on your computer. You will use the local repository is a clone of the origin repository. You will use it to do your writing.
Getting set up to contribute to a GitHub repository requires a few additional pieces of software:
- GitHub Desktop: a visual controller for Git. This is recommended for beginners. Git is also fully operational from a command terminal.
- Open up GitHub Desktop and click on
File>Clone repository. - Switch over to the URL tab and enter the repository URL ending in
.git - Choose a local path (i.e. the location on your computer where you want the files to be stored)
- Click on
Clone
It's useful to keep this program running whenever your writing or making edits to any MSE-Core files.
Whenever you set out to make edits or create new sections, it is useful to create a branch for your new content. In GitHub Desktop, click on Branch in the top bar and name the new branch with something descriptive for others to know what's happening (example: readme-typo):
Every change you make will be tracked in GitHub Desktop. Here's an example where you can see the file that's been changed and the lines in the file where the changes occurred:
Writing, editing, or making changes to files won't be added to the local repository history until you commit them. Now that you've created a branch, you can commit your changes using GitHub Desktop:
Making changes to your local repository does not have any affect on the origin repository until you publish your branch to GitHub and make a pull request.
Once you are satified with changes you've made and you've committed them to your new branch, click on Publish branch in GitHub Desktop.
You can now switch over to the origin repository on GitHub to see your branch waiting to be added. Click on Compare and Pull Request to start the process.
Every pull request should have a name that tells the reviewer what's happening. In the description field (where it says Leave a comment) it is helpful to reference an issue if one exists.
Once the pull request has been submitted, a reviewer will look at your changes and merge your pull request if it looks good or request changes if necessary.