Contributing code

Documentation of the code that supports the ACCESS-NRI catalog and how it fits together can be found in the Catalog management section. Contributions to code are welcome.

If you’d like to contribute code, please start by opening an issue here describing what you would like to contribute and why. Repo maintainers might discuss the issue with you a little and then invite you to submit a “pull request”.

Submitting pull requests

Code contributions are handled through “pull requests” on GitHub. The following describes how to go about making your contributions and submitting a pull request.

1. Fork this respository.

2. Clone your fork locally, connect your repository to the upstream (main project), and create a branch to work on. It’s good practice to include the issue number of the issue that motivated your pull request at the start of your branch name:

   $ git clone git@github.com:YOUR_GITHUB_USERNAME/access-nri-intake-catalog.git
   $ cd access-nri-intake-catalog
   $ git remote add upstream git@github.com:ACCESS-NRI/access-nri-intake-catalog.git
   $ git checkout -b <issue#_description> main
   

   Note

   The above assumes that you have ssh keys set up to access GitHub. If you don’t, replace git@github.com: with https://github.com/.

3. Make your code changes, and test them. The easiest way to do this is to run:

   pixi run test
   

   This will allow you to select which python version you want to run your tests against, and will handle all dependency management for you. If you wish to alter the test execution (eg. to increase verbosity or alter flags), you can do:

   pixi shell
   

   and then interact with tests directly - as if you were in a conda or virtual environment. pixi shell will drop you into a subshell in which pixi has set up your virtual environment. Alternatively, you can do:

   pixi run $CMD
   

   Finally, if you wish to create a conda environment file to follow a more classic development workflow, you can do:

   pixi run dump-conda-env
   

   This will create a file called env.yml in the root of the repository that you can use to create a conda environment from the dependencies defined in the pixi workspace.

4. This project uses ruff for linting and black to format code . We use pre-commit to ensure these have been run. We also use mypy for type checking. Please set up commit hooks by running the following. This will mean that ruff and black are run whenever you make a commit:

   pixi run pre-commit-install
   

   You can also run pre-commit manually at any point to format your code:

   pixi run pre-commit
   

   In addition, you can use any of the following commands to run the various linters and type checkers manually:

   pixi run ruff
   pixi run black
   pixi run mypy
   

   mypy will require you to run pixi run mypy-setup first.

5. Continue making and committing your edits, including adding docstrings to functions, updating the documentation where appropriate, and adding unit tests to check that your contributions are doing what they’re suppose to. Please try to follow numpydoc style for docstrings. To run the test suite:

   pixi run test
   

   This project has both unit tests and integration tests. Integration tests are disabled by default due to computational expense, and can only be run on Gadi. To run the full test suite, including integration tests, run:

   pixi run test-e2e
   

6. Once you are happy with your contribution, go here and open a new pull request to merge your branch of your fork with the main branch of the base.