Github workflow

GoalThis is an exercise to highlight how a Github workflow would be. It is a mock up, so do not

expect things to work. However it should give a realistic feeling of what the user will have to do

to setup his environment and propose changes.

It's not in any mean complete, and it's mostly to gather feedback on the actual steps, and how

we can simplify them.

Account setupGiven Github is an external company, the first thing to do is to create an account there and to

map your Github account to your CERN one. Users need to go to:

https://alisw.cern.ch/alice-github/login

In case you don’t have a github account, it will askyou to create one:

notice you do not need a paying one.

In case you have one, login and authorise ALICE SWto read your user name.

This will map your github username to your CERN user account and will need to be doneonly once.

Installing hub

hub is a command-line wrapper for git that makes you better at GitHub.

On OSX:

$ brew install hub

On Linux:

- Use the precompiled releases: https://github.com/github/hub/releases

Fork repositoryGo fork both AliRoot and AliPhysics. You can do so by going to:

- https://github.com/alisw/AliPhysics/fork

NOTE: current repositories are dummy packages, for the sole purpose of demonstrating how

things would work. The privacy / license issues have to be discussed and agreed before we can

do anything here.

User setup:Initial setup:

git config --global user.name <First Name> <Last Name>git config --global user.email <Your-Email-Address>git config --global user.github <Your-Just-Created-GitHub-Account>

Password-less login- SSH key (see https://help.github.com/articles/generating-an-ssh-key/)

- Credential helper (https://help.github.com/articles/caching-your-github-password-in-git/)

Work area setup- If you use aliBuild, you can simply use

aliBuild init AliRoot,AliPhysics

to clone your repositories .

- If you want to do it by hand, please make sure you do the following:

cd ~/alicehub clone alisw/AliPhysics

With this you will be able to build / run on your local machine.

If you want to contribute back you will need to add your personal repository

cd ~/alice/AliPhysicshub fork

What worked for others

Creating your first Pull RequestLet's say you now have a development to AliPhysics you want to propose for inclusion. This is

done with a Pull Request. In order to create a pull request you need to do the following:

- Push the changes you have to your repository, so that they become public.

git push <your-username> master

- You can continue doing this until you are happy with your changes. Once you are, you can

request inclusion in the official sources with:

hub pull-request

Web Based workflowThe same can be achieved via the web GUI.

- Create the pull request itself by going to https://github.com/<your username>/AliPhysics and

clicking on "New Pull Request":

Review the proposed changes and if you are satisfiedclick on create a pull request

Enter some text describing your development

Review processOnce you are done, the review process starts, hopefully leading to a merge. An automated script

will run tests and post a message for the following cases:

- Test pass, you have right to merge.

- Test do not pass, you will be asked to update.

- Test pass, but the changes touch a file which you are not allowed to change.

Review process: successful tests

Review process: failed tests

Review process: authorisation required

Why I think PRs are better

No more repository disruption: minimal tests must pass.

Web based workflow (you can also edit code from the web, not shown here), less difficult

to memorise by youngsters.

Code and discussions about it in the same place.

Why I think GitHub is better

De-facto standard, we can expect in a few years students arriving at CERN to already

have a Github account.

Support comes from a company that is an established market leader, weekends are not

"best effort" for Github (unlike CERN).

We already know it scales to our needs (other experiments / HEP projects are using it).

Double accounts IMHO is a non issue. People have plenty of accounts already and I've

never seen someone complaining about having to use Gmail. People use what is better,

not what is CERN.

Git allows for easy transition from one provider to another in case of disaster.

Unresolved problems with github- Form CERN, of course, git clone gitlab.cern.ch will be faster (1 time operation, though).

- Privacy: having AliPhysics as a private repository is not feasible on Github. That said, if we sayAliPhysics is GPL, we cannot expect privacy.

TODO:Test with India, Korea, China, US, Indonesia, Taiwan, similar places.

Approval workflow

Build logs