Skip to content

Commit

Permalink
Merge pull request #339 from tovrstra/contrib-centralize
Browse files Browse the repository at this point in the history 
Refer to central contributing guide and add code of conduct
  • Loading branch information
@tovrstra
tovrstra authored Jun 18, 2024
2 parents dc6f97c + ba2ca35 commit a127856
Show file tree
Hide file tree
Showing 3 changed files with 64 additions and 232 deletions.
266 changes: 34 additions & 232 deletions CONTRIBUTING.rst
View file
Original file line number Diff line number Diff line change
@@ -1,251 +1,53 @@
We'd love you to contribute.
Here are some practical tips to help you get started.

This document assumes that you are familiar with `Bash`_ and `Python`_.
If you are not familiar with git or GitHub,
we recommend that you take a look at the `GitHub Guides <https://guides.github.com/>`_
or this `Git Book <https://git-scm.com/book/en/v2>`_.


Development setup
-----------------

The following instructions will create a local clone of the IOData Git repository
that is suitable for development.
It is assumed that you have Python 3.9 or later installed on your system.

The commands below are provided as a guideline to get a working development setup.
Feel free to adapt them to your personal preferences.

- For Linux or macOS:

.. code-block:: bash
git clone [email protected]:theochem/iodata.git
cd iodata
python -m venv venv
source venv/bin/activate
pip install -e .[dev]
pre-commit install
The manual activation of the virtual environment with ``source venv/bin/activate``
has to be repeated every time you open a new terminal window, which is impractical.
We recommend using `direnv`_ to automate the activation of the virtual environment.
After installing and setting up direnv, you can configure it for IOData as follows:

.. code-block:: bash
echo 'source venv/bin/activate' > .envrc
direnv allow
Now, the virtual environment is always activated when you change to the ``iodata`` directory.

- For Windows: ...


Git and GitHub configuration
----------------------------

- If you don't already have an SSH key pair, create one using the following terminal command:
..
: IODATA is an input and output module for quantum chemistry.
:
: Copyright (C) 2011-2019 The IODATA Development Team
:
: This file is part of IODATA.
:
: IODATA is free software; you can redistribute it and/or
: modify it under the terms of the GNU General Public License
: as published by the Free Software Foundation; either version 3
: of the License, or (at your option) any later version.
:
: IODATA is distributed in the hope that it will be useful,
: but WITHOUT ANY WARRANTY; without even the implied warranty of
: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
: GNU General Public License for more details.
:
: You should have received a copy of the GNU General Public License
: along with this program; if not, see <http://www.gnu.org/licenses/>
:
: --
.. code-block:: bash
ssh-keygen -t rsa -b 4096 -C "[email protected]" -f ${HOME}/.ssh/id_rsa_github_com
An empty passphrase is convenient and should be fine.
This will generate a private and a public key in ``${HOME}/.ssh``.

- Upload your *public* SSH key to `<https://github.com/settings/keys>`_.
This is a single long line in ``${HOME}/.ssh/id_rsa_github_com.pub``,
which you can copy and paste into your browser.

- Configure SSH to use this key pair for authentication when pushing branches to GitHub.
Add the following to your ``.ssh/config`` file:

.. code-block::
# Do not allow SSH to try all keys, as SSH servers only accept a few attempts.
# Keys must be specified for each host.
IdentitiesOnly yes
Host github.com
Hostname github.com
ForwardX11 no
IdentityFile %d/.ssh/id_rsa_github_com
(Make sure you have the correct path to the private key file.)

- Configure Git to use the name and email address associated with your GitHub account:
We'd love you to contribute.
Here are some practical tips to help you get started.

.. code-block:: bash
For IOData, you can follow the general
`QC-Devs Contributing Guide <https://github.com/theochem/.github/blob/main/CONTRIBUTING.md>`_.

git config --global user.name "Your Name"
git config --global user.email "[email protected]"
When following that guide, you only need to take into account these specifics for IOData:

- Create a fork of the project, using the `GitHub Fork feature`_.
Add your fork as a second remote to your local repository,
for which we will use the short name ``mine`` below, but any short name will do:
- The repository URL is: [email protected]:theochem/iodata.git
- To run all tests locally, you can use the following commands:

.. code-block:: bash
git remote add mine [email protected]:<your-github-account>/iodata.git
Github work flow
----------------

1. If you want to make changes,
please open a GitHub issue first, or search for an existing issue,
so we can discuss it before you code:

- Use the issue to explain what you want to accomplish and why.
This often saves a lot of time and effort in the long run.
- Also use the issue also to plan your changes.
Try to solve only one problem at a time,
rather than fixing multiple problems and adding different features at once.
Small changes are easier to manage, also for the reviewer in the last step below.
- Finally, mention in the corresponding issue when you are working on it.
Avoid duplicate efforts by assigning yourself to the issue.

Once you have determined what changes need to be made to the source code,
you can proceed with the following steps.
(It is assumed that you have created the development setup above.)


2. Create a new branch, with a name that indicates the purpose of your change:

.. code-block:: bash
git checkout -b new-feature
3. Make changes to the source,
for which the following section discusses conventions, recommendations and guidelines.


4. Verify that all tests pass and that the documentation still builds without warnings or errors:

.. code-block:: bash
# Run tests excluding those marked as slow.
pytest -m "not slow"
# Build the documentation.
(cd docs; make html)
# Finally, if the above steps all pass, run the slow tests.
pytest -m slow
The first command already performs the majority of the tests,
but only takes a few seconds to complete.
The next two are also useful, but take more time.
They are only worth trying if the first one works.

5. Commit your changes using ``git commit``.

You will notice that ``pre-commit`` checks for and possibly fixes minor problems.
If it finds something (even if is automatically fixed), it will abort the commit.
This gives you a chance to fix those problems or check the automatic fixes first.
When you are happy with all the cleanup, run ``git commit`` again.

When prompted, write a meaningful commit message.
The first line is a short summary, written in the imperative mood.
Optionally, this can be followed by blank line and a longer description.
We follow the `Pansini Guide`_ style for commit messages.
This makes it easier to generate changelogs and to understand the history of the project.


6. Push your branch to your forked repository on GitHub:

.. code-block:: bash
git push mine -u new-feature
A link should appear in the terminal that will take you to the next step.


7. Make a pull request from your ``new-feature`` branch in your forked repository
to the ``main`` branch in the original repository.


8. Wait for the GitHub Actions to complete.
These should pass.
Typically, someone should review your pull request within a few days or weeks.
Ideally, the review will result in minor corrections.
We'll do our best to avoid major issues in step 1.


General code guidelines
-----------------------

Code contributions are the most common type of contribution.
We welcome all types of contributions,
including bug fixes, new features, and documentation updates.
All code contributions should follow the guidelines below.


1. Code should be well-written
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In general, we follow the `PEP 8`_ style guide for Python code.
Most style conventions are taken care off by pre-commit.
If you have it installed as described above, the basics are covered.

We strive to write compact and elegant Python code
that is not fully addressed by the linters configured in pre-commit.
This is one of the points we look for when reviewing a pull request.


2. Code should be well-documented
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- All functions and classes (except tests) should have a docstring
explaining what they do and how to use them.
- We encourage the use of mathematical equations in docstrings, using LaTeX notation.
- We do not encourage the use of example code in docstrings,
as it can become outdated and difficult to maintain.
Instead, we encourage the use stand-alone examples that can be executed and tested separately.
- We use `type hinting` to document the types of function (and method) arguments and return values.
- We use `NumPy's docstring format`_, except that types are documented with type hints.
- We recommend using `semantic line breaks`_ when writing comments or documentation.
This improves the readability of ``git diff`` when reviewing changes.
- Your code will be read by other developers, so it should be easy to understand.
If a part of the code seems complex, it should have comments explaining what it does.
(When in doubt, add a comment!)
Good comments emphasize the intent of the code, rather than literally describing it.


3. Code should be tested
^^^^^^^^^^^^^^^^^^^^^^^^

- All code should be tested.
We use `pytest`_ for testing.

- When you add new code, you should also add tests for it.
- If you fix a bug, you should also add a test that fails without and passes with your fix.
- Use ``np.testing.assert_allclose`` and ``np.testing.assert_equal``
to compare floating-point and integer NumPy arrays, respectively.
``np.testing.assert_allclose`` can also be used for comparing floating point scalars.
In all other cases (not involving floating point numbers),
the simple ``assert a == b`` works just as well, and is more readable.
See `numpy.testing`_ for more details.

- We use `codecov`_ in most of our packages to check the code coverage of our tests.
Please make sure that your code is well-tested and that the coverage does not decrease.


4. Code should be consistent
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Code needs to be consistent with the rest of the codebase.
This makes it easier to review and maintain.
This includes:

- Variable names, function names, and class names should be consistent
with the rest of the codebase.
- Most QC-Devs repositories use `atomic units`_ internally.
We ask that you try to preserve this (for consistency), but still document units.
- Even more, variable names should be consistent across QC-Devs packages.
We are in the process of making a glossary, but for now,
please take a look at the existing codes on `GitHub <https://github.com/theochem>`_ and try to match them.

We value your contributions and appreciate your efforts to improve QC-Devs packages.
By following these guidelines, you can ensure smoother collaboration and enhance the overall quality of the project.
The sections below describe how to contribute to features that are specific to IOData.
These are not covered in the general QC-Devs Contributing Guide.


Adding a new file format
Expand Down
29 changes: 29 additions & 0 deletions docs/code_of_conduct.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
..
: IODATA is an input and output module for quantum chemistry.
:
: Copyright (C) 2011-2019 The IODATA Development Team
:
: This file is part of IODATA.
:
: IODATA is free software; you can redistribute it and/or
: modify it under the terms of the GNU General Public License
: as published by the Free Software Foundation; either version 3
: of the License, or (at your option) any later version.
:
: IODATA is distributed in the hope that it will be useful,
: but WITHOUT ANY WARRANTY; without even the implied warranty of
: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
: GNU General Public License for more details.
:
: You should have received a copy of the GNU General Public License
: along with this program; if not, see <http://www.gnu.org/licenses/>
:
: --
.. _code_of_conduct:

Code of Conduct
===============

Please refer to the
`QC-Devs Code of Conduct <https://github.com/theochem/.github/blob/main/CODE_OF_CONDUCT.md>`_
1 change: 1 addition & 0 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,7 @@ Developer Documentation
:maxdepth: 2

contributing
code_of_conduct

API Reference
^^^^^^^^^^^^^
Expand Down

0 comments on commit a127856

Please sign in to comment.