Skip to content

Latest commit

 

History

History
169 lines (114 loc) · 6.88 KB

CONTRIBUTING.md

File metadata and controls

169 lines (114 loc) · 6.88 KB
Raw

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.
    • If the change applies to all generated driver bindings, put the change into the ALL section
    • If it only applies to a single driver binding, put the change in the section associated with that driver
    • 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.

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.