New feature, bug fix, etc.

If you want domutils to be modified in any way, start by opening an issue on github.

1. Create an issue on domutils github page. We will discuss the changes to be made and define a strategy for doing so.

2. Once the issue is created, fork the project. This will create your own github repo where you can make changes.

3. On your computer, clone the source code and go in the package directory

   git clone git@github.com:<your-username>/domutils.git
   cd domutils
   

4. Create a new branch whose name is related to the issue you opened at step 1 above. For example:

   git checkout -b #666-include-cool-new-feature
   

5. Create a clean Anaconda development environment and activate it. You will need internet access for this.

   conda env create --name domutils_dev_env -f docs/environment.yml
   conda activate domutils_dev_env
   

6. It is a good practice to start by writing a unit test that will pass once your feature/bugfix is correctly implemented. Look in the

   test/
   

   directories of the different _domutils_ modules for examples of such tests.

7. Modify the code to address the issue. Make sure to include examples and/or tests in the docstrings.

8. If applicable, describe the new functionality in the documentation.

9. Modify the files:

   VERSION
   CHANGELOG.md
   

   To reflect your changes.

10. Run unittest

    python -m unittest discover
    

11. Run doctest

    cd docs
    make doctest
    

    Make sure that there are no failures in the tests.

    Note that the first time you run this command internet access is required as the test data will be downloaded from zenodo .

12. If you modified the documentation in functions docstrings, you probably want to check the changes by creating your local version of the documentation.

    cd docs
    make html
    

    You can see the output in any web browser pointing to:

    domutils/docs/_build/html/
    

13. While you are working, it is normal to commit changes several times on you local branch. However, before you push to your fork on github, it is probably a good idea to squash all you intermediate commits into one, or a few commits, that clearly link to the issue being worked on. The resulting squashed commit should pass the tests.

14. Once you are happy with the modifications, push the new version on your fork on github

    git push -u origin #666-include-cool-new-feature
    

15. From the github web interface, create a pull request to me. We will then discuss the changes until they are accepted and merged into the master branch.

Test data

Data used in the examples and for running tests can be obtained by running

./download_test_data.sh

in the main directory of this package. This creates a test_data/ directory containing all the test data.