Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
210 lines (144 loc) · 6.49 KB

CONTRIBUTING.md

File metadata and controls

210 lines (144 loc) · 6.49 KB

Contributing to systemlink-enterprise-examples

Contributions to systemlink-enterprise-examples are welcome from all!

systemlink-enterprise-examples is managed via git, with the canonical upstream repository hosted on GitHub.

systemlink-enterprise-examples 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.

Development Setup

This project uses Poetry for dependency management and includes automated tasks via Poe.

Getting Started with Poetry

  1. Install Poetry if you haven't already:

    # On Windows (PowerShell)
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -

# On macOS/Linux
curl -sSL https://install.python-poetry.org | python3 -

  2. Install project dependencies:

    poetry install

  3. Activate the virtual environment:

    poetry shell

Available Poe Tasks

The project includes several automated tasks that you can run using Poetry and Poethepoetry:

  • poetry run poe test - Run the test suite using pytest
  • poetry run poe lint - Run flake8 linting on the codebase
  • poetry run poe check - Check code formatting with Black (without making changes)
  • poetry run poe format - Format code with Black
  • poetry run poe types - Run mypy type checking on the codebase

Recommended Development Workflow

Before submitting a pull request, ensure your code passes all checks:

# Format your code
poetry run poe format

# Run linting
poetry run poe lint

# Run type checking
poetry run poe types

# Run tests
poetry run poe test

You can also run all checks at once:

poetry run poe format && poetry run poe lint && poetry run poe types && poetry run poe test

Commit Message Convention

This project uses Conventional Commits for automated versioning and changelog generation of the nisystemlink_examples Python package.

When conventional commits matter:

  • Commits to the nisystemlink_examples/ package code
  • Changes to tests/, pyproject.toml, or the CI workflow
  • When merged to the main branch

For other contributions (examples, documentation, etc.), conventional commit format is optional but still encouraged for consistency.

Commit Message Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Common Types and Version Bumps

  • fix: - A bug fix (triggers a PATCH version bump: 0.1.0 → 0.1.1)

    fix: correct calculation error in test result processing fix(simulator):
handle empty response from API endpoint

  • feat: - A new feature (triggers a MINOR version bump: 0.1.0 → 0.2.0)

    feat: add support for querying test results by date range feat(testdata): add
batch delete functionality for test results

  • feat!: or BREAKING CHANGE: - A breaking change (triggers a MAJOR version bump: 0.1.0 → 1.0.0)

    feat!: remove deprecated create_result method

    Or with a footer:

    feat: redesign simulator API

BREAKING CHANGE: The create_result method has been removed. Use
create_results_and_steps instead.

Other Common Types (no version bump)

  • docs: - Documentation changes only
  • style: - Code style changes (formatting, whitespace, etc.)
  • refactor: - Code refactoring without changing functionality
  • test: - Adding or updating tests
  • chore: - Maintenance tasks, dependency updates, etc.
  • ci: - CI/CD configuration changes

Examples

# Patch release (0.1.0 → 0.1.1)
git commit -m "fix: handle empty response from API endpoint"

# Minor release (0.1.0 → 0.2.0)
git commit -m "feat: add batch delete functionality for test results"

# Major release (1.0.0 → 2.0.0) - use commit editor for multi-line
git commit
# Then in the editor:
# feat!: redesign simulator API with new parameter structure
#
# BREAKING CHANGE: Removed create_result(), use create_results_and_steps()

What triggers an automated release:

When commits following the conventional format are merged to main and affect:

  • nisystemlink_examples/** (package source code)
  • tests/** (test files)
  • pyproject.toml (package configuration)
  • .github/workflows/python-package.yml (CI/CD workflow)

The package will be automatically versioned, tagged, and published to PyPI.

Security scanning

Contributors within NI/Emerson: See the security scanning reference for information on security scanning tools, workflows, and best practices.

Contributors outside of NI/Emerson: If you are having issues resolving a vulnerability identified on your PR, consult with a code owner to understand your options for resolution.

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 systemlink-enterprise-examples is licensed.