-
Notifications
You must be signed in to change notification settings - Fork 288
Public Contributing
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.
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.
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
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.
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.
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.
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.
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
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.
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 :)
There are two possible cases, depending on how massive your modification is.
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.
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 !