diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e15581d0..d3209e1b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,6 +9,8 @@ repository hosted on [GitHub](https://github.com/ni/nitypes-python/). contribute, you will need to create a GitHub account, fork this project, push a branch with your changes to your project, and then submit a pull request. +## Signing Off Commits + Please remember to sign off your commits (e.g., by using `git commit -s` if you are using the command line client). This amends your git commit message with a line of the form `Signed-off-by: Name Lastname `. Please @@ -23,25 +25,47 @@ See [GitHub's official documentation](https://help.github.com/articles/using-pul To contribute to this project, it is recommended that you follow these steps: +1. Ensure you have [python](https://www.python.org) version 3.11.9 or newer [installed](https://www.python.org/downloads/). 1. Ensure you have [poetry](https://python-poetry.org/) - [installed](https://python-poetry.org/docs/#installation) -2. Fork the repository on GitHub. -3. Install `nitypes` dependencies using `poetry install` -4. Run the regression tests on your system (see Testing section). At this point, if any tests fail, - do not begin development. Try to investigate these failures. If you're unable to do so, report an - issue through our [GitHub issues page](http://github.com/ni/nitypes-python/issues). -5. Write new tests that demonstrate your bug or feature. Ensure that these new tests fail. -6. Make your change. -7. Run all the regression tests again (including the tests you just added), and confirm that they - all pass. -8. Run `poetry run ni-python-styleguide lint` to check that the updated code follows NI's Python - coding conventions. If this reports errors, first run `poetry run ni-python-styleguide fix` in - order to sort imports and format the code with Black, then manually fix any remaining errors. -9. Run `poetry run mypy` to statically type-check the updated code. -10. Send a GitHub Pull Request to the main repository's `main` branch. GitHub Pull Requests are the - expected method of code collaboration on this project. - -# Testing + version 2.1.3 or newer [installed](https://python-poetry.org/docs/#installation). +1. If you do not have write access to the repo fork the repository on GitHub. +1. Install `nitypes` dependencies using `poetry install --with docs`. +1. Perform [Contributor Quality Assurance Activities](#contributor-quality-assurance-activities) +1. If all of the tests and checks covered under + [Contributor Quality Assurance Activities](#contributor-quality-assurance-activities) pass, + proceed to the next step. + If you encounter any failures do not begin development. Instead, try to resolve + those failures, and go back to the previous step. If you are unable to resolve the failures, + report an issue through our [GitHub issues page](http://github.com/ni/nitypes-python/issues). +1. Write new tests that demonstrate your bug or feature. Run regression tests. + Ensure that the new tests fail. +1. Make your change. Remember to sign off your commits as described + [above](#signing-off-commits). +1. Perform [Contributor Quality Assurance Activities](#contributor-quality-assurance-activities) +1. If all of the tests and checks covered under + [Contributor Quality Assurance Activities](#contributor-quality-assurance-activities) pass, + proceed to the next step. Otherwise, fix the failures and go back to the previous step. +1. Send a GitHub Pull Request to the main repository's `main` branch. GitHub Pull Requests are + the expected method of code collaboration on this project. +1. Look at the checks on the checks on the Conversation tab in the PR. + + Note that if you are using a fork of the repo, the `Test Results` check will not complete due to a known issue (#243). + + If any of the checks fails, attempt to fix the failures by changing the code. + +## Contributor Quality Assurance Activities + +As a contributor, you are expected to perform the following quality assurance activities: +1. Perform regression tests per [Regression Tests](#regression-tests) section below. +1. Perform static analysis checks per [Static Analysis Checks](#static-analysis-checks) +section below. +1. If your changes will cover documentation generated from the code, generate that + documentation per + [Documentation Generated from the Code](#documentation-generated-from-the-code) section. +1. If you are concerned that your changes may have negative impact on performance, + perform benchmark test per [Benchmark Tests](#benchmark-tests) + +## Regression Tests In order to be able to run the `nitypes` regression tests, your setup should meet the following minimum requirements: @@ -49,15 +73,56 @@ requirements: - Machine has a supported version of CPython or PyPy installed. - Machine has [poetry](https://python-poetry.org/) installed. -To run the `nitypes` regression tests, run the following command in the root of the distribution: +To perform regression tests, run `poetry run pytest -v` in the root of the distribution. -```sh -$ poetry run pytest -v -``` +## Static Analysis Checks + +Static analysis is performed in several steps, as set forth below. Run each of the commands listed below in the root of the distribution. + +1. Run `poetry run ni-python-styleguide lint` to check that the updated code follows NI's Python + coding conventions. If this reports errors, first run `poetry run ni-python-styleguide fix` + to sort imports and format the code with Black, then manually fix any ring errors. +1. Run `poetry run mypy`. If there are any failures, fix them. +1. Run `poetry run pyright`. If there are any failures, fix them. +1. Run `poetry run bandit -c pyproject.toml -r src/nitypes`. If there are any failures, fix them. + +# Special Considerations + +## Documentation Generated from the Code + +The following information is relevant if you are making changes that +will impact documentation generated from the code. + +To generate documentation from the code, run `poetry run sphinx-build docs docs/_build --builder html --fail-on-warning` in the root of the distribution. + +If there are any failures, fix them. + +To review generated documentation, run `start docs\_build\index.html` from the +root of the distribution. + +## Benchmark Tests + +The PR pipeline will perform benchmark tests. The following information +is provided in case you expect that your change will impact performance, +or in case benchmark checks performed by the PR pipeline fail. + +To perform benchmark tests do the following: + * For the first run, prior to making any changes, run the + command `poetry run pytest -v tests/benchmark --benchmark-save=base` + * For the second and subsequent runs, after making changes, run the + command `poetry run pytest -v tests/benchmark --benchmark-compare=0001` + + To learn more about benchmark tests, refer + to https://pytest-benchmark.readthedocs.io/en/latest/comparing.html # Example Development Workflow +The example belows applies when you are making changes that will +not impact documentation generated from code and that will not impact +code performance. If your situation is different, add appropriate +steps per documentation above. ``` +# Create a fork # Create a new branch git fetch git switch --create users/{username}/{branch-purpose} origin/main @@ -65,27 +130,30 @@ git switch --create users/{username}/{branch-purpose} origin/main # Install the project dependencies poetry install --with docs -# ✍ Make source changes +# Run regression tests +poetry run pytest -v -# Run the analyzers -- see files in .github/workflows for details +# Run static analysis checks poetry run nps lint poetry run mypy poetry run pyright poetry run bandit -c pyproject.toml -r src/nitypes -# Run the tests +# ✍ Add regression tests. +# Run regression tests poetry run pytest -v -# Run the benchmarks -# Compare benchmark before/after a change -# see https://pytest-benchmark.readthedocs.io/en/latest/comparing.html -# Run 1: --benchmark-save=some-name -# Run N: --benchmark-compare=0001 -poetry run pytest -v tests/benchmark +# ✍ Make source changes +# Remember to sign off commits -# Build and inspect the documentation -poetry run sphinx-build docs docs/_build --builder html --fail-on-warning -start docs\_build\index.html +# Run regression tests +poetry run pytest -v + +# Run static analysis checks +poetry run nps lint +poetry run mypy +poetry run pyright +poetry run bandit -c pyproject.toml -r src/nitype ``` # Publishing on PyPI