forked from Nixtla/nixtla
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: add contributing file (Nixtla#236)
- Loading branch information
Showing
1 changed file
with
43 additions
and
89 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,133 +2,87 @@ | |
|
|
||
| ## Did you find a bug? | ||
|
|
||
| - Ensure the bug was not already reported by searching on GitHub under Issues. | ||
| - If you're unable to find an open issue addressing the problem, open a new one. | ||
| Be sure to include a title and clear description, as much relevant information | ||
| as possible, and a code sample or an executable test case demonstrating the | ||
| expected behavior that is not occurring. | ||
| - Be sure to add the complete error messages. | ||
| * Ensure the bug was not already reported by searching on GitHub under Issues. | ||
| * If you're unable to find an open issue addressing the problem, open a new one. Be sure to include a title and clear description, as much relevant information as possible, and a code sample or an executable test case demonstrating the expected behavior that is not occurring. | ||
| * Be sure to add the complete error messages. | ||
|
|
||
| ## Do you have a feature request? | ||
|
|
||
| - Ensure that it hasn't been yet implemented in the `main` branch of the | ||
| repository and that there's not an Issue requesting it yet. | ||
| - Open a new issue and make sure to describe it clearly, mention how it improves | ||
| the project and why its useful. | ||
| * Ensure that it hasn't been yet implemented in the `main` branch of the repository and that there's not an Issue requesting it yet. | ||
| * Open a new issue and make sure to describe it clearly, mention how it improves the project and why its useful. | ||
|
|
||
| ## Do you want to fix a bug or implement a feature? | ||
|
|
||
| Bug fixes and features are added through pull requests (PRs). | ||
|
|
||
| ## PR submission guidelines | ||
|
|
||
| - Keep each PR focused. While it's more convenient, do not combine several | ||
| unrelated fixes together. Create as many branches as needing to keep each PR | ||
| focused. | ||
| - Ensure that your PR includes a test that fails without your patch, and passes | ||
| with it. | ||
| - Ensure the PR description clearly describes the problem and solution. Include | ||
| the relevant issue number if applicable. | ||
| - Do not mix style changes/fixes with "functional" changes. It's very difficult | ||
| to review such PRs and it most likely get rejected. | ||
| - Do not add/remove vertical whitespace. Preserve the original style of the file | ||
| you edit as much as you can. | ||
| - Do not turn an already submitted PR into your development playground. If after | ||
| you submitted PR, you discovered that more work is needed - close the PR, do | ||
| the required work and then submit a new PR. Otherwise each of your commits | ||
| requires attention from maintainers of the project. | ||
| - If, however, you submitted a PR and received a request for changes, you should | ||
| proceed with commits inside that PR, so that the maintainer can see the | ||
| incremental fixes and won't need to review the whole PR again. In the | ||
| exception case where you realize it'll take many many commits to complete the | ||
| requests, then it's probably best to close the PR, do the work and then submit | ||
| it again. Use common sense where you'd choose one way over another. | ||
| ## PR submission guidelines | ||
|
|
||
| * Keep each PR focused. While it's more convenient, do not combine several unrelated fixes together. Create as many branches as needing to keep each PR focused. | ||
| * Ensure that your PR includes a test that fails without your patch, and passes with it. | ||
| * Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable. | ||
| * Do not mix style changes/fixes with "functional" changes. It's very difficult to review such PRs and it most likely get rejected. | ||
| * Do not add/remove vertical whitespace. Preserve the original style of the file you edit as much as you can. | ||
| * Do not turn an already submitted PR into your development playground. If after you submitted PR, you discovered that more work is needed - close the PR, do the required work and then submit a new PR. Otherwise each of your commits requires attention from maintainers of the project. | ||
| * If, however, you submitted a PR and received a request for changes, you should proceed with commits inside that PR, so that the maintainer can see the incremental fixes and won't need to review the whole PR again. In the exception case where you realize it'll take many many commits to complete the requests, then it's probably best to close the PR, do the work and then submit it again. Use common sense where you'd choose one way over another. | ||
|
|
||
| ### Local setup for working on a PR | ||
|
|
||
| #### Clone the repository | ||
|
|
||
| - HTTPS: `git clone https://github.com/Nixtla/nixtla.git` | ||
| - SSH: `git clone [email protected]:Nixtla/nixtla.git` | ||
| - GitHub CLI: `gh repo clone Nixtla/nixtla` | ||
| * HTTPS: `git clone https://github.com/Nixtla/nixtla.git` | ||
| * SSH: `git clone [email protected]:Nixtla/nixtla.git` | ||
| * GitHub CLI: `gh repo clone Nixtla/nixtla` | ||
|
|
||
| #### Set up a conda environment | ||
| The repo comes with an `environment.yml` file which contains the libraries needed to run all the tests. In order to set up the environment you must have `conda` installed, we recommend [miniconda](https://docs.conda.io/en/latest/miniconda.html). | ||
|
|
||
| The repo comes with an `environment.yml` file which contains the libraries | ||
| needed to run all the tests. In order to set up the environment you must have | ||
| `conda` installed, we recommend | ||
| [miniconda](https://docs.conda.io/en/latest/miniconda.html). | ||
|
|
||
| Once you have `conda` go to the top level directory of the repository and run | ||
| the following lines (we recommend to use `python=3.10` for development, | ||
| currently `python>=3.11` is not supported): | ||
| Once you have `conda` go to the top level directory of the repository and run the following lines (we recommend to use `python=3.10` for development): | ||
|
|
||
| ``` | ||
| conda env create -f environment.yml | ||
| conda create -n nixtlats python=3.10 | ||
| conda activate nixtlats | ||
| conda env update -f environment.yml | ||
| ``` | ||
|
|
||
| #### Install the library | ||
| Once you have your environment setup, activate it using `conda activate nixtlats` and then install the library in editable mode using `pip install -e ".[dev]"` | ||
|
|
||
| Once you have your environment setup, activate it using | ||
| `conda activate nixtlats` and then install the library in editable mode using | ||
| `pip install -e ".[dev]"` | ||
| #### Set Up TimeGPT token | ||
| This library uses `python-dotenv` for development. To set up your TimeGPT token, add the following lines to your `.env` file: | ||
|
|
||
| #### Install git hooks | ||
| ``` | ||
| TIMEGPT_TOKEN=<your token> | ||
| ``` | ||
|
|
||
| Before doing any changes to the code, please install the git hooks that run | ||
| automatic scripts during each commit and merge to strip the notebooks of | ||
| superfluous metadata (and avoid merge conflicts). | ||
| Please write to `[email protected]` if you're insterested in contributing to this project to get access to your TimeGPT token. | ||
|
|
||
| #### Install git hooks | ||
| Before doing any changes to the code, please install the git hooks that run automatic scripts during each commit and merge to strip the notebooks of superfluous metadata (and avoid merge conflicts). | ||
| ``` | ||
| nbdev_install_hooks | ||
| ``` | ||
|
|
||
| ### Preview Changes | ||
|
|
||
| You can preview changes in your local browser before pushing by using the | ||
| `nbdev_preview`. | ||
| You can preview changes in your local browser before pushing by using the `nbdev_preview`. | ||
|
|
||
| ### Building the library | ||
|
|
||
| The library is built using the notebooks contained in the `nbs` folder. If you | ||
| want to make any changes to the library you have to find the relevant notebook, | ||
| make your changes and then call: | ||
|
|
||
| The library is built using the notebooks contained in the `nbs` folder. If you want to make any changes to the library you have to find the relevant notebook, make your changes and then call: | ||
| ``` | ||
| nbdev_export | ||
| ``` | ||
|
|
||
| ### Linters | ||
|
|
||
| This project uses a couple of linters to validate different aspects of the code. | ||
| Before opening a PR, please make sure that it passes all the linting tasks by | ||
| following the next steps. | ||
|
|
||
| - `mypy nixtlats/` | ||
| - `flake8 --select=F nixtlats/` | ||
|
|
||
| ### Running tests | ||
|
|
||
| If you're working on the local interface you can just use | ||
| `nbdev_test --n_workers 1 --do_print --timing`. | ||
| If you're working on the local interface you can just use `nbdev_test --n_workers 1 --do_print --timing`. | ||
|
|
||
| ### Cleaning notebooks | ||
|
|
||
| Since the notebooks output cells can vary from run to run (even if they produce | ||
| the same outputs) the notebooks are cleaned before committing them. Please make | ||
| sure to run `nbdev_clean --clear_all` before committing your changes. If you | ||
| clean the library's notebooks with this command please backtrack the changes you | ||
| make to the example notebooks `git checkout nbs/examples`, unless you intend to | ||
| change the examples. | ||
| Since the notebooks output cells can vary from run to run (even if they produce the same outputs) the notebooks are cleaned before committing them. Please make sure to run `nbdev_clean ` before committing your changes. | ||
|
|
||
| ## Do you want to contribute to the documentation? | ||
|
|
||
| - Docs are automatically created from the notebooks in the `nbs` folder. | ||
| - In order to modify the documentation: | ||
| 1. Find the relevant notebook. | ||
| 2. Make your changes. | ||
| 3. Run all cells. | ||
| 4. If you are modifying library notebooks (not in `nbs/examples`), clean all | ||
| outputs using `Edit > Clear All Outputs`. | ||
| 5. Run `nbdev_preview`. | ||
| 6. Clean the notebook metadata using `nbdev_clean`. | ||
| * Docs are automatically created from the notebooks in the `nbs` folder. | ||
| * In order to modify the documentation: | ||
| 1. Find the relevant notebook. | ||
| 2. Make your changes. | ||
| 3. Run all cells. | ||
| 5. Run `nbdev_preview`. | ||
| 6. Clean the notebook metadata using `nbdev_clean`. | ||
|
|
||