Skip to content

Latest commit

 

History

History
256 lines (201 loc) · 11.9 KB

CONTRIBUTING.md

File metadata and controls

256 lines (201 loc) · 11.9 KB

Contributing to nimi-python

Contributions to nimi-python are welcome from all!

nimi-python is managed via Git, with the canonical upstream repository hosted on GitHub.

nimi-python 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.

See GitHub's official documentation for more details.

Setting up your system

In order to have the ability to build and run the tests you will need a few things to be set up on your system.

Windows:

  • Install and enable Windows Subsystem for Linux
  • Install the following in Windows Subsystem for Linux:
    • GNU Make: sudo apt-get install make
    • zip: sudo apt-get install zip
    • 64-bit Python -- Use the version that build_test uses. See envlist definition in tox.ini

macOS:

  • Install Xcode
  • Install command line developer tools
  • Install Python
    • Use the version that build_test uses. See envlist definition in tox.ini

Linux:

  • Install Python: sudo apt-get install python3-pip
    • Use the version that build_test uses. See envlist definition in tox.ini

All:

Once your system has been setup with the above, install required additional Python modules using PyPI.

    sudo pip install pytest tox --upgrade

Building nimi-python

  1. Fork the repository on GitHub and clone it to your local system.

  2. On a terminal, navigate to the nimi-python root directory. Then run

    tox

    It will do the following, for each driver:

    • Validate the code generator and build scripts
    • Generate Python bindings
    • Generate RST documentation
    • Create installer packages
    • Run flake8
    • Generate HTML documentation
    • Iterate over all installed and supported Python versions and run unit tests

  3. To clean everything and start fresh

     tox -e clean

Running the system tests

nimi-python includes system tests that exercise the Python modules against the real driver runtimes. Our CI includes invoking nimibot to run these tests for you on PRs pending admin approval.

But it is recommended that during development you run the system tests locally, especially if the areas of the code affected by your changes may impact interaction with the driver runtimes.

In order to run the nimi-python system tests locally:

Install the corresponding driver runtimes.

Download and install the latest versions for the supported driver runtimes from ni.com:

  • NI-DCPower
  • NI-Digital Pattern Driver
  • NI-DMM
  • NI-FGEN
  • NI-SCOPE
  • NI-SWITCH
  • NI Switch Executive

NI-ModInst and NI-TClk are included with the above, they have no separate installers.

Install build artifacts

After you have successfully built nimi-python, install the locally built PyPI packages using PyPI:

find generated | grep \.whl | xargs sudo python3 -m pip install -U

Once the Python bindings are installed, run the system tests for the desired driver. For example:

pytest src/nidmm/system_tests -c generated/nidmm/tox-system_tests.ini

You can also use tox to run the system tests for the desired driver, using all installed Python versions. For example:

tox -c generated/nidmm/tox-system_tests.ini

Contributing

After you've verified that you can successfully build and run system tests for nimi-python, you may begin contributing to to the project.

  1. If applicable, write a failing test for the new feature / bugfix.
    • If you are modifying the code generator, write new NI-FAKE unit tests. If the new functionality requires changes to metadata, apply those to NI-FAKE.
    • If you are modifying driver-specific metadata, write new system tests.
  2. Make your change.
  3. Verify all tests, including the new ones, pass.
  4. Update CHANGELOG.md for customer-visible changes.
    • Put the change into the Unreleased section for each package that it applies to.
    • If it's a common change for all the packages, include the (Common) string before the newly added change in [CHANGELOG.md].
    • DO NOT MENTION: Internal-only changes like refactors or test improvements.
  5. Commit modifications to generated files.
  6. On GitHub, send a New pull request to the main repository's master branch. GitHub pull requests are the expected method of code collaboration on this project.

Release Process

  1. Pre-Release Steps
    1. Checkout the master branch and pull down the latest changes 
      git checkout master
# Discard all local changes
git restore .
# Merge changes from upstream
git pull upstream master
    2. Build master to ensure it is in a good state and ready for release 
      tox -e clean
tox
    3. Ensure no commits are made on ni/nimi-python/master until the release is complete
    4. Create and checkout a branch for release-related changes
    5. Perform Version Bump (If Needed)
      • If you need to upgrade the major or minor versions, include any of the following parameters:
        • --increment-major-version - To increment the major version of package. This will update the version to (N+1).X.X.dev0
        • --increment-minor-version - To increment the minor version of package. This will update the version to X.(N+1).X.dev0
          • Example: python3 tools/build_release.py --increment-minor-version
      • If you need to update the version for any specific driver(s), include the drivers parameter. By default, all drivers will be considered. For example: bash python3 tools/build_release.py --drivers nidcpower --increment-minor-version
      • Commit to branch
    6. Update CHANGELOG.md
      • For packages that are releasing:
        • Delete empty (i.e. No changes) sub-sections under "Unreleased" section
        • Remove the Unreleased section from the TOC if there are no changes for the package.
        • Change the "Unreleased" header to the version of the release
        • Change [Unreleased] in TOC to the version of the release
      • Commit to branch
    7. Update release versions
      • python3 tools/build_release.py --update-for-release
        • For each module, this will drop the .devN from our versions in config_addon.py and update the LATEST_RELEASE versions to match.
        • If you need to release any specific module(s), include the drivers parameter. For example: 
          python3 tools/build_release.py --drivers nidcpower --update-for-release
      • Commit to branch
    8. Clean and build to update generated files with new version
      • python3 tools/build_release.py --build
      • Commit to branch
    9. Create a pull request
      • It should contain all the changes made so far
      • Get the pull request reviewed but DO NOT merge to master yet
  2. Release Steps
    1. Wait until the pull request has been approved
    2. Upload the releases to PyPI
      • python3 tools/build_release.py --upload
      • If you need to upload any specific module(s), include the drivers parameter. For example: 
        python3 tools/build_release.py --drivers nidcpower --upload
      • You will need to type in your PyPI credentials
    3. Merge the pull request to origin/master
    4. For each package released, create a release on GitHub using the module's portion from the changelog for this release for the description
      • The release tag should be named as follows: MODULE_NAME-version.
        • Example: nidcpower-1.5.0.
        • This tag format allows the individual Read the Docs projects to determine whether a release applies to them.
      • Add the ZIP files under generated/examples for each module (not just the releasing one) as a release artifact.
        • Internal test code will only look for the latest release tag and expect it to have examples attached for any module
      • This should trigger the check_latest_release workflow. Check the results before continuing.
  3. Post-Release Steps
    1. Create and checkout another branch for post-release changes
    2. Update the module version for a patch version upgrade. This will update the version to X.X.(N+1).dev0
      • python3 tools/build_release.py --increment-patch-version
      • If you need to update any specific module(s), include the drivers parameter. For example: 
        python3 tools/build_release.py --drivers nidcpower --increment-patch-version
      • Commit to branch
    3. Clean and build to update generated files with new version
      • python3 tools/build_release.py --build
      • Ensure that all changes made as part of build command are specific to intended drivers.
      • Commit to branch
    4. Update changelog
      • Copy Unreleased section from the bottom of the changelog. Modify the package name in the example and TOC. Paste the modified section at the top of intended package's changelog and add a corresponding link to it in the package's TOC.
      • Commit to branch
    5. Create a pull request containing post-release changes and get it merged

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 nimi-python is licensed.