diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 6bca22c6..143ba3c2 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,14 +1,6 @@ -## Type of changes - -- [ ] Bug fix -- [ ] New feature -- [ ] Documentation / docstrings -- [ ] Tests -- [ ] Other - ## Checklist -- [ ] I've formatted the new code by running `poetry run pre-commit run --all-files --show-diff-on-failure` before committing. +- [ ] I've formatted the new code by running `hatch run dev:format` before committing. - [ ] I've added tests for new code. - [ ] I've added docstrings for the new code. diff --git a/docs/contributing.md b/docs/contributing.md index 10be7812..578626b4 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -72,36 +72,19 @@ you through every detail! Always use a `feature` branch. It's good practice to avoid work on the ``main`` branch of any repository. -4. We use [Poetry](https://python-poetry.org/) for packaging and dependency management, and project requirements are in ``pyproject.toml``. We suggest using a [virtual environment](https://docs.python-guide.org/dev/virtualenvs/) for -development. For those using Apple Silicon chips, we advise using [Conda miniforge](https://github.com/conda-forge/miniforge). Once the virtual environment is activated, run: +4. We use [Hatch](https://hatch.pypa.io/latest/) for packaging and dependency management. Project requirements are in ``pyproject.toml``. To install GPJax into a Hatch virtual environment, run: ```bash - $ poetry install + $ hatch env create ``` At this point we recommend you check your installation passes the supplied unit tests: ```bash - $ poetry run pytest + $ hatch run dev:all-tests ``` -5. Install the pre-commit hooks. - - ```bash - $ pre-commit install - ``` - - Please ensure you have done this before committing any files. If - successful, this will print the following output `pre-commit installed at - .git/hooks/pre-commit`. - -6. At this point you can manually run the pre-commit hooks with the following command: - - ```bash - poetry run pre-commit run --all-files - ``` - -7. Add changed files using `git add` and then `git commit` files to record your +5. Add changed files using `git add` and then `git commit` files to record your changes locally: ```bash @@ -122,7 +105,7 @@ development. For those using Apple Silicon chips, we advise using [Conda minifor $ git push -u origin my-feature ``` -8. Go to the GitHub web page of your fork of the GPJax repo. Click the 'Pull +6. Go to the GitHub web page of your fork of the GPJax repo. Click the 'Pull request' button to send your changes to the project's maintainers for review. @@ -159,7 +142,7 @@ request, we recommend you check the following: accepted. Test coverage can be checked with: ```bash - $ poetry run pytest tests --cov=./ --cov-report=html + $ hatch run dev:coverage ``` Navigate to the newly created folder `htmlcov` and open `index.html` to view diff --git a/docs/installation.md b/docs/installation.md index b711d70b..73de5282 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -31,7 +31,7 @@ hardware acceleration support as detailed in the ```bash git clone https://github.com/thomaspinder/GPJax.git cd GPJax - poetry install + hatch shell create ``` !!! tip @@ -45,5 +45,5 @@ hardware acceleration support as detailed in the and recommend you check your installation passes the supplied unit tests: ```bash - poetry run pytest tests/ + hatch run dev:all-tests ``` diff --git a/static/CONTRIBUTING.md b/static/CONTRIBUTING.md index 5df3f455..578626b4 100644 --- a/static/CONTRIBUTING.md +++ b/static/CONTRIBUTING.md @@ -1,147 +1,152 @@ -# Guidelines for Contributing +# Contributing -GPJax welcomes contributions from interested individuals or groups. These -guidelines help explain how you can contribute to the library +## How can I contribute? -There are 4 main ways of contributing to the library (in descending order of -difficulty or scope): +GPJax welcomes contributions from interested individuals or groups. There are +many ways to contribute, including: + +- Answering questions on our [discussions + page](https://github.com/JaxGaussianProcesses/GPJax/discussions). +- Raising [issues](https://github.com/JaxGaussianProcesses/GPJax/issues) related to bugs + or desired enhancements. +- Contributing or improving the + [docs](https://github.com/JaxGaussianProcesses/GPJax/tree/main/docs) or + [examples](https://github.com/JaxGaussianProcesses/GPJax/tree/master/docs/nbs). +- Fixing outstanding [issues](https://github.com/JaxGaussianProcesses/GPJax/issues) + (bugs). +- Extending or improving our [codebase](https://github.com/JaxGaussianProcesses/GPJax). -- Adding new or improved functionality to the existing codebase -- Fixing outstanding issues (bugs) with the existing codebase. They range from - low-level software bugs to higher-level design problems. -- Contributing or improving the documentation (`docs`) or examples - (`gpjax/docs/nbs`) -- Submitting issues related to bugs or desired enhancements ## Code of conduct As a contributor to GPJax, you can help us keep the community open and inclusive. Please read and follow our [Code of -Conduct](https://github.com/thomaspinder/GPJax/blob/master/.github/CODE_OF_CONDUCT.md). +Conduct](https://github.com/JaxGaussianProcesses/GPJax/blob/master/.github/CODE_OF_CONDUCT.md). -# Opening issues and getting support +## Opening issues and getting support Please open issues on [Github Issue -Tracker](https://github.com/thomaspinder/GPJax/issues/new/choose). +Tracker](https://github.com/JaxGaussianProcesses/GPJax/issues/new/choose). Here you can +mention You can ask a question or start a discussion in the [Discussion -section](https://github.com/thomaspinder/GPJax/discussions) on Github. +section](https://github.com/JaxGaussianProcesses/GPJax/discussions) on Github. -# Contributing code via pull requests +## Contributing to the source code -Please submit patches via pull requests. +Submitting code contributions to GPJax is done via a [GitHub pull +request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). +Our preferred workflow is to first fork the [GitHub +repository](https://github.com/JaxGaussianProcesses/GPJax), clone it to your local +machine, and develop on a _feature branch_. Once you're happy with your changes, +install our `pre-commit hooks`, `commit` and `push` your code. -The preferred workflow for contributing is to fork the [GitHub -repository](https://github.com/thomaspinder/GPJax), clone it to your local -machine, and develop on a feature branch. Once you are ready to commit your -changes, install the pre-commit hooks with `pre-commit install` and the commit -and push your code as usual. +**New to this?** Don't panic, our [guide](#step-by-step-guide) below will walk +you through every detail! -## Steps: +!!! attention "Note" -1. Fork the [project repository](https://github.com/thomaspinder/GPJax) by - clicking on the 'Fork' button near the top right of the main repository page. - This creates a copy of the code under your GitHub user account. + Before opening a pull request we recommend you check our [pull request checklist](#pull-request-checklist). -2. Clone your fork of the GPJax repo from your GitHub account to your local - disk, and add the base repository as a remote: - ```bash - $ git clone git@github.com:/GPJax.git - $ cd GPJax - $ git remote add upstream git@github.com:GPJax.git - ``` +### Step-by-step guide: -3. Create a `feature` branch to hold your development changes: +1. Click [here](https://github.com/JaxGaussianProcesses/GPJax/fork) to Fork GPJax's + codebase (alternatively, click the 'Fork' button towards the top right of + the [main repository page](https://github.com/JaxGaussianProcesses/GPJax)). This + adds a copy of the codebase to your GitHub user account. - ```bash - $ git checkout -b my-feature - ``` +2. Clone your GPJax fork from your GitHub account to your local disk, and add + the base repository as a remote: + ```bash + $ git clone git@github.com:/GPJax.git + $ cd GPJax + $ git remote add upstream git@github.com:GPJax.git + ``` - Always use a `feature` branch. It's good practice to never routinely work on - the `master` branch of any repository. +3. Create a `feature` branch to hold your development changes: -4. Project requirements are in `requirements.txt`. + ```bash + $ git checkout -b my-feature + ``` + Always use a `feature` branch. It's good practice to avoid + work on the ``main`` branch of any repository. - We suggest using a [virtual - environment](https://docs.python-guide.org/dev/virtualenvs/) for development. - Once the virtual environment is activated, run: +4. We use [Hatch](https://hatch.pypa.io/latest/) for packaging and dependency management. Project requirements are in ``pyproject.toml``. To install GPJax into a Hatch virtual environment, run: - ```bash - $ pip install -e . - $ pip install -r requirements-dev.txt - ``` + ```bash + $ hatch env create + ``` -5. Install the pre-commit hooks. Please **ensure you do this before committing - any files**. This can be done by executing the following: - ```bash - $ pre-commit install - ``` - If successful, this will print the following output `pre-commit installed at - .git/hooks/pre-commit`. + At this point we recommend you check your installation passes the supplied unit tests: -6. Develop the feature on your feature branch. When you're done editing, format the new code with - ```bash - $ poetry run pre-commit run --all-files --show-diff-on-failure - ``` - If any errors are reported, fix them and re-run the command. + ```bash + $ hatch run dev:all-tests + ``` -7. Check all tests are passing - ```bash - poetry run pytest tests --n auto - ``` - If any tests fail, fix them and re-run the command. +5. Add changed files using `git add` and then `git commit` files to record your + changes locally: -8. Add changed files using `git add` and then `git commit` files: + ```bash + $ git add modified_files + $ git commit + ``` + After committing, it is a good idea to sync with the base repository in case + there have been any changes: - ```bash - $ git add modified_files - $ git commit - ``` + ```bash + $ git fetch upstream + $ git rebase upstream/main + ``` - to record your changes locally. After committing, it is a good idea to sync - with the base repository in case there have been any changes: + Then push the changes to your GitHub account with: - ```bash - $ git fetch upstream - $ git rebase upstream/main - ``` + ```bash + $ git push -u origin my-feature + ``` - Then push the changes to your GitHub account with: +6. Go to the GitHub web page of your fork of the GPJax repo. Click the 'Pull + request' button to send your changes to the project's maintainers for + review. - ```bash - $ git push -u origin my-feature - ``` +### Pull request checklist -9. Go to the GitHub web page of your fork of the GPJax repo. Click the 'Pull - request' button to send your changes to the project's maintainer for review. +We welcome both complete or "work in progress" pull requests. Before opening +one, we recommended you check the following guidelines to ensure a smooth review +process. -## Pull request checklist +**My contribution is a "work in progress":** -We recommended that your contribution complies with the following guidelines -before you submit a pull request: +Please prefix the title of incomplete contributions with `[WIP]` (to indicate a +work in progress). WIPs are useful to: -- If your pull request addresses an issue, please use the pull request title to - describe the issue and mention the issue number in the pull request - description. This will make sure a link back to the original issue is created. + 1. Indicate you are working on something to avoid duplicated work. + 2. Request broad review of functionality or API. + 3. Seek collaborators. -- All public methods must have informative docstrings +In the description of the pull request, we recommend you outline where work +needs doing. For example, do some tests need writing? -- Please prefix the title of incomplete contributions with `[WIP]` (to indicate - a work in progress). WIPs may be useful to (1) indicate you are working on - something to avoid duplicated work, (2) request broad review of functionality - or API, or (3) seek collaborators. +**My contribution is complete:** -- All other tests pass when everything is rebuilt from scratch. +If addressing an issue, please use the pull request title to describe the issue +and mention the issue number in the pull request description. This will make +sure a link back to the original issue is created. Then before making your pull +request, we recommend you check the following: -- Documentation and high-coverage tests are necessary for enhancements to be - accepted. + - Do all public methods have informative docstrings that describe their + function, input(s) and output(s)? + - Do the pre-commit hooks pass? + - Do the tests pass when everything is rebuilt from scratch? + - Documentation and high-coverage tests are necessary for enhancements to be + accepted. Test coverage can be checked with: -- Code with good test, check with: + ```bash + $ hatch run dev:coverage + ``` - ```bash - $ pip install -r requirements-dev.txt - $ pytest tests --cov=./ --cov-report=html - ``` + Navigate to the newly created folder `htmlcov` and open `index.html` to view + the coverage report. -#### This guide was derived from [PyMC's guide to contributing](https://github.com/pymc-devs/pymc/blob/main/CONTRIBUTING.md) +This guide was derived from [PyMC's guide to +contributing](https://github.com/pymc-devs/pymc/blob/main/CONTRIBUTING.md).