Skip to content

Latest commit

 

History

History
152 lines (96 loc) · 6.39 KB

CONTRIBUTING.md

File metadata and controls

152 lines (96 loc) · 6.39 KB
Raw

Contributing and Development

Note

This project supports Python 3.9 as the minimum version. All development should be done in the minimum supported version to ensure compatibility. Automated tests should prevent compatibility issues (as they are tested on all versions and platforms), but save yourself potential trouble.

We welcome contributions! To contribute to this repository, please follow these steps:

Development Environment

This project uses the Just command runner, which is installed as part of the development dependencies. Run just to see the available recipes that you can use.

Command Description
just install Installs the development environment
just install-precommit Installs and updates the pre-commit hooks environment
just lock-requirements Recompiles requirements.txt from dev-dependencies in pyproject.toml
just clean Removes caches, builds, reports, and other generated files
just build Builds and checks the distribution package
just version Releases version info and lists commits since the last release
just test Runs tests with coverage report
just update-snapshots Updates snapshots (known results) for pytest

Recipes are defined in the /Justfile. Feel free to suggest new ones.

Set Up Development Environment

Clone the repository:

git clone https://github.com/espressif/cz-plugin-espressif.git

Create and activate the virtual environment:

python -m venv venv && . venv/bin/activate

Install the locally editable Python project with development and test dependencies:

pip install -e '.[dev,test]'

Test that the plugin is recognized and responds:

cz example

Install pre-commit hooks:

just install-precommit

Code Structure

  • Readable Code Structure: Keep your code well-organized and readable. The main logic should be placed in the default rule function, while implementation details should be separated into helper functions. Avoid nested if statements and unnecessary else statements to maintain code clarity and simplicity.

  • Remove Debug Statements: Ensure that all debug statements are removed before submitting your pull request (PR) for review.

  • Automated Tests: This project uses a testing strategy that compares the output generated by commitizen + this plugin against known and expected snapshots. If you run pytest --snapshot-update, it updates the snapshots, adding new ones for new test cases and removing those for deleted tests.

  • Testing Tool: Run pytest frequently during development to ensure your code is functioning as expected.

Documentation and Maintenance

  • Changelog: The CHANGELOG.md is generated automatically using commitizen + the czespressif plugin from commit messages. There is no need to manually update the changelog. Instead, focus on writing informative and clear commit messages, which will be reflected in the release notes. When possible, include the scope in your commit message.

  • Documentation: Regularly review and update the documentation to ensure it stays up-to-date.

  • PR/MR Descriptions and Documentation: When making contributions, clearly describe any changes or new features in both the PR (Pull Request on GitHub) or MR (Merge Request on GitLab) description and the project documentation. If you're modifying the output style, please include a thumbnail of the new style.

Testing

This project uses a test strategy comparing the output generated by commitizen + the czespressif plugin against known and expected snapshots.

Manual Testing

Run tests with:

pytest

If you intend to update snapshots (visuals, style), ensure you describe the reason for this change in the GitHub PR description.

Update snapshots with:

pytest --snapshot-update

This will update snapshots, adding new ones for new test cases and removing those for deleted tests.

Before submitting a pull request, ensure your changes pass all the tests. While this project does not aim for 100% test coverage, we are aiming for strong coverage and continually work to improve it. If you add new functionality, it should be reflected and tested appropriately.

Manual Testing (External Project)

To test this plugin in another project (which must have some git history and tags), run:

pip install -e <absolute-path-to-your-local-clone-of-this-project>

Next, set the commitizen configuration in the pyproject.toml of the external project. Once that's done, you can run commitizen commands such as cz changelog and cz bump --dry-run to observe how they modify the changelog.

Automated Testing

We use a GitHub Workflow to test this plugin across different Python versions (3.9 - 3.12) and platforms (MacOS, Linux, Windows) with every update of Pull Request and when merged to default branch.

Pull Request Guidelines

Please ensure that your PR is complete before requesting a review (or switching from Draft to Ready for Review):

  • All checks and tests must pass.
  • All DangerJS PR linter warnings must be addressed.
  • Your changes have to be well documented.
  • If you've added new functionality, please describe why it’s useful and how it was tested.

There is a Pull Request template to help guide you in writing a proper PR description.

Important

Incomplete PRs can't be reviewed — please be respectful of the reviewers' time and avoid submitting incomplete work.

👏Thank you for your contributions.