-
Notifications
You must be signed in to change notification settings - Fork 52
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
217e9e8
commit af2f86e
Showing
4 changed files
with
115 additions
and
135 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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:<your GitHub handle>/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:<your GitHub handle>/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). |