Skip to content

Public Contributing

baudren edited this page Mar 3, 2014 · 5 revisions

Setting up git locally

Whether you are familiar with git or not, this section will explain you how to set up git and work with the CLASS code locally.

Basic

First off, you need git ! Git is a version control system, like svn, but with many important differences. If you are lucky enough to have a linux, simply use your package manager. Mac users will want to have a look at this website, and go through the old versions (1.8.0.1) if your version of Mac Os X is below 10.5. You can also use macports, think or homebrew.

Git only handles the local part, but to share our work with others, we need a central server, with authentification and so on. We chose Github to do this. You need then to configure git on your machine to work well with this site.

Git Configuration

As it is often the case, there is a hidden file in your home called ~/.gitconfig that holds all the options you want to use when working with git. Copy paste the below text in this file, and replace username entries with appropriate values, and the line with vimdiff and vim with your own choice of editors.

[user]
    name = FirstName SecondName
    email = class-user@university.somewhere
[color]
    ui = auto
[merge]
    log = true
    tool = vimdiff
[core]
    editor = vim
[alias]
    co = checkout
    st = status
    br = branch
    re = remote
    ci = commit
    tree = log --decorate --graph --date=relative --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(cyan)<%an>%Creset' master
    tree-clean = log --oneline --decorate --graph --first-parent --date=relative --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(cyan)<%an>%Creset' master

Setting up CLASS locally

Two ways of interacting with the code

There are two ways of participating to CLASS development. The first one, that involves Github, is more suited if you will want to create large modifications, with several commits, and allow us to incorporate it into the main code.

If your goal is instead to work on your own project, using CLASS, and its updates, and from time to time committing a small modification, you can use the other method, that do not require Github to start with. It makes communicating a modification slightly more cumbersome, but still manageable.

In any case, try to keep as much as possible in mind these guidelines:

  • one branch is one concept, do not implement several different small things in one single branch
  • Comment the code
  • one commit should be one modification, summarized in a meaningful commit messages (a one, short line summary, then after a blank line, more details if needed)

Finally, please keep in mind that there is an embryo of an automated test suite, in the python/ subfolder, called test_class.py. It is far from perfect for many reason, one being that it also tests the wrapper and not only the C code, but without too much efforts, you should be able to write an automated test of your modification to ensure that it works as intended. It uses the nose framework, which you would need to install.


A) Forking the repository on Github

For the first solution to work, you will need a Github account. It is free under certain restrictions.

  • For free, you will have the possibility to create 5 public repositories, but no private ones.
  • If you are a (PhD)-student, you can send them a nice e-mail, and you will also be able to create a few private repositories as well.

You can then fork the class_public repository, which will create your own version of CLASS, with all the history. You can then check out this code locally, delete the master branch for added security, and start implementing a modification on some other branch.

B) Cloning the repository locally

You are now ready to clone the public repository locally, by going into a suitable folder, and do

$ git clone https://username@github.com/lesgourg/class_public.git class

where username is your Github account name. You should be asked your Github password too. Then, go to the just created directory:

$ cd class/
$ git branch
* master

As you can see, you are only following the master branch, as intended.


Developing modifications to CLASS

Starting

Whether you chose to fork from Github or to clone directly locally, you should have in any case a local copy of the code, containing only the master branch.

There exist on the private repository a devel branch, that is used internally to develop the code. The policy is that modifications are done only to the devel branch, and merged into the master when reaching a stable enough state. You can see this by doing

$ git tree

You will see, starting from version 2.0.0 (hash 782f5a8), a branched structure of commits. All the commits on the left hand side of the branch correspond to commits to the master branch, that are actually mergers from the development branch.

The merge is done with the git flag --no-ff, which creates a new commit for the merging, and keeps the information that this work comes from another branch.

To look only at the stable commits, simply issue:

$ git tree-clean

You will be presented to only these commits. These ones are the one you should branch off if you want to develop your own version of class. Imagine you want to implement feature, you can do the following:

$ git pull
$ git branch feature
$ git checkout feature

The first command makes sure you are up to date with the master branch. You then create a new branch called feature, and go on this last one by checking-out on it.

You can then develop your code.

Keeping up to date with the master

This is to be done only in case of a severe hotfix that really affects
the way the code works. Otherwise, only merging from the feature to
the devel is acceptable.

Imagine you worked a bit, committed several modifications to your feature branch. However, we pushed also some modifications to the master, for instance some patch, that might affect you.

To keep up to date, simply checkout the master branch and pull from the repository

$ git co master
$ git pull

This will fast-forward the master branch (since you did not edit it). You can then checkout your branch, and merge the master.

$ git co feature
$ git merge master

Sending us modifications

If you - or we - think that the work you have done might benefit more persons than just you, we would like to be able to merge it into the main code, to make it available to all.

Below are the details on how to do this depending on your choice in the previous paragraphs.

A) If you forked the project on Github

All the changes you made were committed to your origin remote repository. You want to now push these changes to the upstream repository, i.e. to the main class repository.

For this, Jesus, I am still needing your input :)

B) If you are working only locally

There are two possible cases, depending on how massive your modification is.

Small Modification

If you only created a few new commits compared to the cloned version, you can then simply create a patch for each commit, and send these patches by e-mail.

As an example, you modified master, and your first commit sha1 code is xxxx. You then committed two additional small modifications.

$ git format-patch xxxx

This will create three files, 0001-first-commit-message.patch, 0002-second-commit.patch, 0003-third-commit.patch. You can send these three files to Julien, that will then merge these into the development branch, to appear on the master branch on the next main release.

Substantial Modification

If your work was more substantial, but its logic is straightforward (for instance, implementing a generic type of modified gravity), it would be nicer to squash your commits into just one, and then create a single patch out of this.

To this end, assuming your modification is based on the commit yyyy (so a commit on master, of the base code, one before the xxxx of the previous example), and that you developed on your master branch, do the following:

$ git branch tempsquash yyyy $ git checkout tempsquash $ git merge --squash master $ git commit (for such a huge modification, I strongly encourage you to use a short and powerful first-line message, and a thorough description underneath) $ git format-patch master

This will create the file 0001-my-short-and-powerful-first-line-message.patch. Send it to us, please !



Questions