contributing.rst 7.16 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12
.. sidebar:: General Information

    .. contents:: :local:

    * :ref:`search`

.. _contributing:

==================
How to contribute?
==================

13 14 15 16
This webpage is actually a repository of files that (typically) document application development efforts during the
pilot projects and Extended Software Development Workshops (ESDWs) of E-CAM. This documentation is completely open
however and we welcome both internal and external contributions. If you would like to contribute to this effort then
please follow the steps below to allow us to include your contribution.
17

18
In any case you will simply be adding a simple text file that uses ReST_ and we have prepared an example to help
19 20 21 22
you get started:

* :ref:`example`

23 24
You will find the example within the repository of this documentation under the directory *example_module*. You should
make a copy of this directory (renaming it) and place it in the appropriate scientific area directory.
25 26 27 28 29 30 31

Contribution Guidelines
=======================

GitLab account
--------------

32 33
If you do not have a (free) GitLab account yet on the E-CAM GitLab service, you'll need to get one via
https://gitlab.e-cam2020.eu/.
34

Alan O'Cais's avatar
Alan O'Cais committed
35
.. note::
36

Alan O'Cais's avatar
Alan O'Cais committed
37 38
  You should also register an SSH public key with GitLab (if you have not already done so), so you can easily clone, push to and pull from your repositories. This can
  be done via https://gitlab.e-cam2020.eu/profile/keys (once you're logged in on GitLab).
39

Alan O'Cais's avatar
Alan O'Cais committed
40
In the following it is assumed that an SSH public key has been registered with GitLab (see note above), the possibility of using the HTTPS protocol
41
to access GitLab is not covered (but is possible).
42

43 44 45 46
Fork the repository
-------------------

Firstly, you'll need to fork the repository on GitLab you want to work with. Go to
Alan O'Cais's avatar
Alan O'Cais committed
47
https://gitlab.e-cam2020.eu/e-cam/E-CAM-Library , and click the grey 'Fork' button either beside or under the repository name (or just click this `fork link <https://gitlab.e-cam2020.eu/e-cam/E-CAM-Library/forks/new>`_).
48

49 50 51 52 53 54 55
Clone your fork of the repository
---------------------------------

Clone your fork of the repository to your favorite workstation.

.. code-block:: bash

56
    git clone ssh://git@gitlab.e-cam2020.eu:10022/<Your GitLab username>/E-CAM-Library.git
57 58 59 60 61

Pull the master branch from the main repository:

.. code-block:: bash

62 63
    cd E-CAM-Library
    git remote add upstream https://git@gitlab.e-cam2020.eu/e-cam/E-CAM-Library.git
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78
    git pull upstream master

Keep your master branch up-to-date
----------------------------------

Make sure you update it every time you create a feature branch (see below):

.. code-block:: bash

    git checkout master
    git pull upstream master

Branching
---------

79 80
Pick a branch name for your work that makes sense, so you can track things easily and make sense if you end up having
several branches in flight at once (each PR is a new branch).
81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100

Examples:

    ``update_gromacs_module``

    ``new_esdw_lammps_module``

    ``industry_devel_module``


Create a feature branch for your work (after updating your master), and check it out

.. code-block:: bash

    git checkout master
    git branch BRANCH_NAME
    git checkout BRANCH_NAME

Make sure to always base your features branches on master!

101 102
If you are working on several things at the same time, try and keep things isolated in separate branches, to keep it
manageable (both for you, and for reviewing your contributions).
103 104 105 106

Contributing module documentation
---------------------------------

107 108 109
Your contribution to this repository will primarily be a module documentation file (this repository is not for source
code, the documentation file will link to source code which is usually somewhere else). There are already several
examples of these in the repository, but we provide a template for a generic module as a guide:
110 111 112 113 114 115 116

.. toctree::
    :glob:
    :maxdepth: 1

    ./example_module/readme

117
After creating the branch, implement your contributions: new modules, enhancements or updates to existing modules, bug
Alan O'Cais's avatar
Alan O'Cais committed
118
fixes, structure changes, whatever you like.
119

Alan O'Cais's avatar
Alan O'Cais committed
120 121 122 123 124 125 126
Make sure to put your work in the appropriate directory. There are 4 scientific
areas in E-CAM and your module is likely most relevant in one of those. Each of these directories has a ``modules``
subdirectory, create a new directory within it to contain all files relevant to your specific module. In the example
below, this directory has been called ``gromacs_gpu``.

Make sure you commit your work, and try to do it in bite-size chunks, so
the commit log remains clear, for example:
127 128 129

.. code-block:: bash

Alan O'Cais's avatar
Alan O'Cais committed
130 131
    git add Classical-MD-Modules/modules/gromacs_gpu/readme.rst
    git commit -m "add details on improved GPU support within GROMACS"
132

133 134 135
Checking your contribution locally
----------------------------------

136
You can locally build the documentation to check that the changes you make look as you expect them. To do this you will
Alan O'Cais's avatar
Alan O'Cais committed
137
need the Sphinx python package to be installed (see this `installation link <http://www.sphinx-doc.org/en/stable/install.html>`_ for
138
information on how to install this tool on your operating system).
139 140 141 142 143 144

.. code-block:: bash

    make html # in root directory of repository
    firefox _build/html/index.html # Use your browser to view the end result

145 146
If you do not have Latex installed on your system you are likely to get related errors. Other (non-latex) errors are
likely to come from your additions. 
147 148 149 150 151 152 153 154 155 156 157 158

Contributing back your input
----------------------------

When you've finished the implementation of a particular contribution, here's how to get it into the main repository.

Push your branch to *your* copy of the repository on GitLab

.. code-block:: bash

    git push origin <BRANCH_NAME>

159 160 161
Issue a *Merge Request* for your branch into the main repository. To do this go to
https://gitlab.e-cam2020.eu/Your_GitLab_Username/E-CAM-Library/merge_requests and select the *New Merge Request*
button.
162

163 164
Make sure the branch you just pushed is selected (not master!) issue a merge request for your branch to the master
branch of the main repository.
165 166 167 168

Updating your contribution
--------------------------

169 170
It is common for there to be updates required to contributions, you do **not** need to open a new Merge Request to do
this. 
171

172 173 174
To update your contribution you update the appropriate files on your contribution branch. Firstly you need to ensure
that you are up to date with the remote repository on GitLab. Make sure you are in the directory of the cloned
repository and then check which branch you want to check out:
175 176 177 178 179 180 181 182

.. code-block:: bash

    git branch # List all available local branches, to include remote branches add the -r flag
    git checkout <BRANCH_NAME> # Check out the branch we want to update 
    git pull origin <BRANCH_NAME> # Make sure we have any updates we made to our own branch
    git pull upstream master # Also pull in any changes to the main repository

Alan O'Cais's avatar
Alan O'Cais committed
183
Now that everything is in sync, you can edit and update your files, when you are finished you commit your changes and
184
push the changes back to GitLab:
185 186 187 188

.. code-block:: bash

    git add modules/gromacs_gpu/readme.rst
189
    git commit -m "update documentation on how to trigger the GPU support"
190 191 192 193 194
    git push origin <BRANCH_NAME>

The Merge  Request will now be automatically updated with the changed files.
    
.. _ReST: http://docutils.sourceforge.net/docs/user/rst/quickref.html