Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
122 lines (92 loc) · 4.93 KB

CONTRIBUTING.md

File metadata and controls

122 lines (92 loc) · 4.93 KB

Contributing to nitypes

Contributions to nitypes are welcome from all!

nitypes is managed via git, with the canonical upstream repository hosted on GitHub.

nitypes follows a pull-request model for development. If you wish to 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.

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 <name.lastmail@emailaddress.com>. Please include all authors of any given commit into the commit message with a Signed-off-by line. This indicates that you have read and signed the Developer Certificate of Origin (see below) and are able to legally submit your code to this repository.

See GitHub's official documentation for more details.

Getting Started

To contribute to this project, it is recommended that you follow these steps:

  1. Ensure you have poetry installed
  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.
  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

In order to be able to run the nitypes regression tests, your setup should meet the following minimum requirements:

  • Machine has a supported version of CPython or PyPy installed.
  • Machine has poetry installed.

To run the nitypes regression tests, run the following command in the root of the distribution:

$ poetry run pytest -v

Example Development Workflow

# Create a new branch
git fetch
git switch --create users/{username}/{branch-purpose} origin/main

# Install the project dependencies
poetry install --with docs

# ✍ Make source changes

# Run the analyzers -- see files in .github/workflows for details
poetry run nps lint
poetry run mypy
poetry run pyright
poetry run bandit -c pyproject.toml -r src/nitypes

# Run the 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

# Build and inspect the documentation
poetry run sphinx-build docs docs/_build --builder html --fail-on-warning
start docs\_build\index.html

Developer Certificate of Origin (DCO)

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or

(b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or

(c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.

(d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.

(taken from developercertificate.org)

See LICENSE for details about how nitypes is licensed.