Contributing code to SIESTA

Fork the official SIESTA repository

If you plan to contribute to SIESTA, it is a good idea to fork the official repository directly on Gitlab. This will greatly help the maintenance of SIESTA in the long run and the communication between its diverse contributors.

Here is how to proceed (a more detailed list follows just after):

1. With your favourite web browser, go to the official SIESTA repository on Gitlab: https://gitlab.com/siesta-project/siesta.
2. Select a namespace to use for the forked project. This should be your Gitlab user name.
3. Wait for the project to be forked.
4. Check that everything is as you expect.
5. Clone the repository and set an upstream remote.

Step 1

When you go to the official SIESTA repository, you should see the following in the upper part of the page:

Click on the fork button located at the top-right part of the screen, as highlighted in the above image with a red ellipse.

Step 2

When forking a repository, you have to specify the namespace to use for the copy of the source repository, as shown in the image below. The namespace is like a domain controlled by a specific user or team. Is is instrumental in defining who can do what on the new repository.

Since Git and Gitlab provide a lot of flexibility to coordinate distributed development efforts, we highly recommend you to create the forked repository under your personal namespace. You still can create team-wise secondary repositories and/or transfer yours to a team in the future should you need it. To use your personal namespace, click on you user avatar, as highlighted above.

Step 3

Once you have clicked on your avatar, Gitlab will create a copy of the official repository in the background and mark the official SIESTA repository as the parent of yours.

Just wait that the operation gets done. It should take a minute at most.

Step 4

You should now see your personal SIESTA repository, as shown below.

Feel free to explore it and check that it contains the baseline information you need.

Step 5

Note: In this section, we will assume that you have registered the SSH key of your computer in your Gitlab settings. If this is not the case yet, please go to the SSH Keys section of your settings first and add the relevant keys there. Gitlab will provide you with instructions on how to do it if you don’t know how to proceed.

Open a terminal and go to the directory from where you will contribute to SIESTA. We will call it my-contribs here. Feel free to rename it as you prefer. To make the upstream SIESTA repository available from your Git work tree, please time the following commands, replacing $GITLAB_USER by your actual Gitlab username:

mkdir ~/my-contribs
cd ~/my-contribs
git clone git@gitlab.com:$GITLAB_USER/siesta.git
cd siesta
git remote add upstream git@gitlab.com:siesta-project/siesta.git
git fetch --all --tags

From this moment on, you will be able to synchronise your branches with the upstream evolution of SIESTA at any time.

Develop a new fix or feature

You can create a branch in your personal SIESTA repository to hold your changes. When you are ready with the implementation, you can create a merge request. The basic picture of forking and creating merge requests is described here.

Happy coding!