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, hep-sf.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.

For simple things, there is an alternative to creating a clone on your local computer: you can use the GitHub editor in the web interface. When you save your changes, this commits your changes and you are asked for commit message. Note that this is really limited to situations where your contribution is limited to only one file as you cannot edit several files and commit them togheter this way. Apart from the management of the Git clone, there workflow for pushing your changes to the project repository remains the same, using pull request.

Sections below give more details on the main steps involved. Examples are based on the HSF web site repository. 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, if you want to use the full workflow with a clone of the GitHub repository on your local computer, 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 will require 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… At some point, 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!