How to contribute¶
Any development work takes place performing pull requests against the current develop
branch.
Prerequisites¶
Make sure you have an account on GitHub and that you have your public SSH key uploaded.
One of two things, either you need to clone the repository, or you need to make sure you have the recent changes in place.
You have the AiiDA-VASP repository present in your local computer. Clone the upstream AiiDA-VASP repository by running:
$ git clone git@github.com:aiida-vasp/aiida-vasp.git
You already have the AiiDA-VASP repository present on your local computer. Check if you already have some changes. From the root folder of the repository run:
$ git status
If you have no changes, good, continue. If you have, try to remember what you have done and if it is worth saving. Issue for instance:
$ git stash
to store what you had changed. These can later be retrieved as long as you do not delete the repository and clone it again. Now, make sure you are on the
develop
branch, i.e.:$ git checkout develop
Make sure you have the recent
develop
branch by running i.e.:$ git pull origin develop
if the upstream AiiDA-VASP repository is stored as
origin
in yourgit
setup.
Typically this upstream repository will be a
remote
calledorigin
. Double check what it is called withgit remote -v
. In the following, we assume this is calledorigin
.Make sure your AiiDA-VASP Python virtual environment is enabled, consult the installation instructions.
Make sure you are ready for development work on the plugin, meaning, you need to make sure you have installed everything you need. Make sure you have installed the plugin in edit mode and that you have enabled the extra
tests
,docs
andpre-commit
options when installing. Execute from the root folder of the clones source code for AiiDA-VASP:$ cd aiida-vasp $ pip install -e .[tests,pre-commit,docs]
Make sure
pre-commit
is enabled by running:$ pre-commit install
Workflow for contributions¶
You should try to follow this workflow when submitting a contribution:
Open an issue describing as best you can the issue and how to fix it (if you know or have some suggestion).
Create a new branch for your suggested changes. Use a short, descriptive name (here, we use the example
my_changes
), i.e.git checkout -b my_changes
Edit/add files.
If you added new files, or renamed, make sure to add them back in (here, example file
new_documentation.rst
) with i.e.git add new_documentation.rst
Verify that you have not forgotten any files and that the changes are as expected with
git status
andgit diff
.Commit the changes:
git commit -am 'My new additions'
. Make sure to give a proper and descriptive commit message. Sometimes it is better not to give the-m
option and only dogit commit -a 'My new additions'
which will bring up your standard editor. There, in the first line you give a header which is the title of the commit. Following is a blank line and then a more extensive description of what is done. Notice that when you issue the commit,pre-commit
will run different checks, in particular for linting. Most likely this will not pass. Please adjust and issue the commit command again until it passes. The same check is done after the code have been pushed. For simplicity one can install tox to make running the pre-commit and any tests much easier, this can be done by runningpip install tox
and then the pre-commit can be run inside tox viatox -e pre-commit
. In a similar way the tests can be locally run viatox -e py{python_version}--aiida_vasp -- --cov=./aiida_vasp --cov-append --cov-report=xml
wherepython_version
is your local python version without the “.”, e.g. 39 for python 3.9.Upload your changes to the main repository:
git push origin my_changes
Create a new pull request. Select your
my_changes
branch as thecompare
branch anddevelop
as thebase
branch.Describe the changes and optionally assign someone to review and approve the commits.