Improved contributor documentation

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 <[email protected]>`. Please
@@ -23,69 +25,135 @@ 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:
 
 - 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
 
 # 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