Contributing

If you would like to contribute to the ligo-raven project via development or reporting issues, please refer to the issues page.

Code changes should be made via merge requests that are reviewed and pass all unittests (including new ones that may need to be added). If you aren’t familiar with git or want a refresher for specific steps, refer to the below step-by-step guide to making code changes.

Setting up your local repository

Firstly, you will want to request permission to make changes to the git repository by becoming a member via Project Information => Members. The next step is to make a personal fork of the ligo-raven project and clone this to your local computer. This is done by finding the fork button on the git repository and following the directions.

Next we can clone this fork to where you want to work, usually a local computer or home directory on a cluster. This can be done via ssh or https using the instructions on your fork (use the https method if you haven’t set up ssh keys with gitlab). Cloning your fork ensures that it is set as the default origin fork rather than the main repo, potentially avoiding accidental pushes to the wrong repo.

For example the https method is:

$ git clone https://git.ligo.org/albert.einstein/raven.git

Once you have your local fork downloaded, enter it and set the main git repository as the upstream:

$ cd raven
$ git remote add upstream https://git.ligo.org/lscsoft/raven/

We can check we have both our origin and upstream forks set up correctly by using the command:

$ git remote -v
origin https://git.ligo.org/albert.einstein/raven (fetch)
origin https://git.ligo.org/albert.einstein/raven (push)
upstream https://git.ligo.org/lscsoft/raven (fetch)
upstream https://git.ligo.org/lscsoft/raven (push)

Next, we should make sure we are able to incorporate the latest changes by using the fetch/rebase method:

$ git checkout master
$ git fetch upstream
$ git rebase upstream/master

Making changes

We should always make a new branch if we want to make changes to the code:

$ git checkout -b my-new-feature upstream/master

We can check we are on a new branch by:

$ git branch
master
* my-new-feature

Now we can make changes to existing files as we please.

Once we are done making changes, we can make a commit and include all file changes by:

$ git commit -a

and giving this commit a name descriptive of the changes. If these changes include new files, we need to add these before making a commit:

$ git add path/to/newfile

We can push these changes to our own fork (origin) by:

$ git push origin

Finally, we can make a merge request, by going to Merge Requests on your local fork or click Create merge request via a pop-up prompt. Follow the instructions and include a description of your changes.

Make sure you also document your changes in CHANGES.rst and include this in your merge request.

Incorporating recent upstream or local changes

If other changes are made and merged before your merge request is finished, the you will need to use incorporate these changes using the fetch/rebase method:

$ git fetch upstream
$ git rebase upstream/master
$ git push origin -f

If there is a conflict, fix the conflict in the appropirate file(s) (remembering to remove the extra text added), add the file(s) and then continue the rebase:

$ git add path/to/file-w-conflict
$ git rebase --continue

Continue this until every conflict has been resolved.

Also, your merge request should only containt a single commit before merging, where you can squash all your commits to the first one by:

$ git rebase -i upstream/master

and replace every pick except the first with f.

Once your changes are reviewed and improved, and pass all tests, it can be merged in the main git repository and be included in the next release.