Contributing Guidelines#

For optimal teamwork, it’s crucial to set clear and pragmatic guidelines upfront, rather than addressing the confusion that arises from overlooking them later. If you’re committed to making impactful contributions, please take a moment to thoroughly review the following guidelines!

Bugs, issues, input, questions, etc#

Please use the issue tracker to share any of the following:

  • Bugs

  • Issues

  • Questions

  • Feature requests

  • Ideas

  • Input

Having these reported and saved in the issue tracker is very helpful to make them properly addressed. Please be as descriptive and neat as possible when opening up an issue. When available, please also attach your I/O data and the full error message.

Developing#

Code contributions can be anything from fixing the simplest bugs, to adding new extensive features or subpackages. If you have written code or want to start writing new code that you think will improve WFacer then please follow the steps below to make a contribution.

Guidelines#

  • All code should have unit tests.

  • Code should be well documented following google style docstrings.

  • All code should pass the pre-commit hook. The code follows the black code style.

  • Additional dependencies should only be added when they are critical or if they are already a smol or a sparse-lm dependency. More often than not it is best to avoid adding a new dependency by simply delegating to directly using the external packages rather than adding them to the source code.

  • Implementing new features should be more fun than tedious.

Installing a development version#

  1. Clone the main repository or fork it and clone clone your fork using git. If you plan to contribute back to the project, then you should create a fork and clone that:

    git clone https://github.com/<USER>/WFacer.git

    Where <USER> is your github username, or if you are cloning the main repository directly then <USER> = CederGroupHub.

  2. Install Python 3.8 or higher. We recommend using python 3.9 or higher: conda.

  3. We recommend developing using a virtual environment. You can do so using conda or using virtualenv.

  4. Install the development version of WFacer in editable mode:

    pip install --verbose --editable .[dev,test]

    This will install the package in editable mode, meaning that any changes you make to the source code will be reflected in the installed package.

Adding code contributions#

  1. If you are contributing for the first time:

    • Install a development version of WFacer in editable mode as described above.

    • Make sure to also add the upstream repository as a remote:

      git remote add upstream https://github.com/CederGroupHub/WFacer.git

    • You should always keep your main branch or any feature branch up to date with the upstream repository main branch. Be good about doing fast forward merges of the upstream main into your fork branches while developing.

  2. In order to have changes available without having to re-install the package:

    • Install the package in editable mode:

      pip install -e .

  3. To develop your contributions you are free to do so in your main branch or any feature branch in your fork.

    • We recommend to only your forks main branch for short/easy fixes and additions.

    • For more complex features, try to use a feature branch with a descriptive name.

    • For very complex feautres feel free to open up a PR even before your contribution is finished with [WIP] in its name, and optionally mark it as a draft.

  4. While developing we recommend you use the pre-commit hook that is setup to ensure that your code will satisfy all lint, documentation and black requirements. To do so install pre-commit, and run in your clones top directory:

    pre-commit install

  5. Make sure to test your contribution and write unit tests for any new features. All tests should go in the WFacer\tests directory. The CI will run tests upon opening a PR, but running them locally will help find problems before:

    pytests tests

  6. To submit a contribution open a pull request to the upstream repository. If your contribution changes the API (adds new features, edits or removes existing features). Please add a description to the change log.

  7. If your contribution includes novel published (or to be published) methodology, you should also edit the citing page accordingly.

Adding examples#

In many occasions novel use of the package does not necessarily require introducing new source code, but rather using the existing functionality, and possibly external packages (that are are requirements) for particular or advanced calculations.

  1. Create a sub-directory with a descriptive name in the docs/src/example_scripts directory.

  2. Implement the functionality with enough sections to carefully describe the background, theory, and steps in the index.rst file.

  3. Once the script is ready, add an entry to the Examples page’s rst file so your example shows up in the documentation.