GitHub for Beginners

Table of Contents:

This pages is a GitHub and Git survival kit for people not familiar with these tools! This is not a documentation or tutorial about these tools. Many excellent ones are already available, including:

GitHUb Workflow

At a first glance, GitHub (and Git) may look complex with their “workflows”. But they are not so much in fact. What makes these tools great is that they allow a clear separation between your personal work and what you decide to show or export. Your personal work, unlike with tools like SVN, can be versionned and you can work on different things in parallel (branches) very easily.

In the HSF web site context, what is shared is what is in the project repository called, hepix-forum.github.io. Your personal environment is made of 2 parts:

With this GitHub workflow, the only repository you need to have write access to on GitHub is your personal repository. This ensures that nothing wrong can happen to the project repository because you are not a Git/GitHub expert.

Sections below give more details on the main steps involved. Note that there is a help available for each Git command that can be displayed with:

git help
git help command

GitHub Account Creation and Configuration

To contribute, you definitely need to have a GitHub account: connect to gitHub and follow the instructions.

Once you have an account, it is recommended to configure your SSK keys that will be used for the authentication: follow the GitHub documentation. Using SSH keys is not a requirement but is recommended: the alternative if you want to contribute is to use https but in this case any interaction with GiHb through the git command may require (depending on your OS) that you enter your password…

Creating your Personal Environment

As explained in the introduction, this involves 2 steps:

Note that adding a remote adds no information to the repository itself.

Making your Changes

This step is about making your changes in your local clone: nothing will be visible on GitHub at this stage. There are many variations of the steps involved here: below are the main/recommanded ones.

Note that you can do the cycle edit/commit as many times as you want, until you are satisfied, before pushing your changes.

Publishing your Changes

Publishing changes involves 2 steps (again!):

After the pull request has been created, all the persons interested in the project repository changes will be notified by email. Everybody can subscribe the repository notifications. At this point, your contribution is open for review: people can comment, suggest changes… When there is an agreement that the contribution is in good shape, somebody with the appropriate permission will merge it in the poject repository (this is a one-click operation).

Note that as soon as a pull request is open, every change that you make to the personal branch that you published (which is the source of the pull request) is published immediately (until the pull request is closed/merged). You cannot create several pull requests with the same source branch.

When the pull request is merged, you can decide to delete your personal branch that was used to make your contribution but there is no real need to do it… It’s a matter of personal taste!