Skip to content

Latest commit

 

History

History
141 lines (96 loc) · 7.87 KB

CONTRIBUTING.md

File metadata and controls

141 lines (96 loc) · 7.87 KB
Raw

Welcome to the esp-hal Contributing Guide

Thank you for considering contributing to our project! Your efforts help make esp-hal a better ecosystem for everyone.

This guide outlines the contribution workflow, from reporting issues and submitting pull requests, to the review process and eventual merger of contributions.

Quick Navigation

New Contributor Guide

Welcome aboard! If you're new to esp-hal or open-source contribution, here are some resources to get you started:

Before adding or changing code, review the esp-rs API guidelines.

Getting Started

Issues: Reporting and Resolving

Reporting a New Issue

Encountered a problem or have an idea? First, check existing issues to avoid duplicates. If your concern is new, use our issue form to submit it.

Working on an Issue

Browse existing issues to find one that resonates with you. Use labels for easier filtering. If you decide to tackle an issue, it's courteous (but not mandatory) to let others know by commenting.

Making Changes: Fork, Edit, and Pull Request

  1. Fork: Start by forking the repository. This keeps the main project safe while you make your changes.
  2. Setup: Ensure you have the latest Rust toolchain via rustup.rs.
  3. Branch: Create a branch in your fork for your changes. Keep your changes focused and limited to a single issue or feature.

What You Should Do:

  • API changes: If your contribution changes the API, please adapt the driver (including module level documentation) and examples accordingly and update the HIL (Hardware-in-the-Loop) tests.
  • Run Related Examples: After making changes, run any affected examples to ensure they build successfully and perform as expected.
  • Manual Testing: For hardware-related changes, manually test your changes on the actual devices when possible. If not, please note it in the corresponding issue, and someone from our team will assist with testing. This is crucial because hardware behavior can sometimes differ from what's simulated or expected.
  • HIL Tests: Ensure that any changes to the API or hardware interaction logic are reflected in the HIL tests located in the hil-test directory. This helps verify the real-world applicability of your changes.

By taking these extra steps to test your contributions, you help maintain the high quality and reliability of esp-hal, ensuring it remains a robust platform for everyone.

Testing Your Contributions

Ensuring the quality and reliability of esp-hal is a shared responsibility, and testing plays a critical role in this process. Our GitHub CI automatically checks the buildability of all examples and drivers within the project. However, automated tests can't catch everything, especially when it comes to the nuanced behavior of hardware interactions. So make sure that the example affected by your change works as expected.

Further steps that can (or should) be taken in testing:

  • Using xtask, build examples for the specified chip.
  • Build the documentation and run the doctests if they have been modified using the build-documentation and run-doc-test commands in xtask.
  • Run the HIL tests locally if changes have been made to them.

Commit Your Updates

Commit your changes once you're satisfied. Review your own work to streamline the review process later. Use rustfmt and cargo clippy to ensure your code adheres to Rust's conventions.

rustup component add rustfmt
rustup component add clippy

We strongly recommend that you format your code before committing to ensure consistency throughout the project. To format all packages in the workspace, run the following command in a terminal from the root of the repository:

cargo xtask fmt-packages

We also recommend using the lint-packages subcommand, which uses cargo clippy and will lint the entire driver in order to catch common mistakes in the code.

cargo xtask lint-packages

This will use rustfmt to ensure that all source code is formatted correctly prior to committing.

Pull Request: From Submission to Merge

  • Fill the pull request template so that we can review your PR. This template helps reviewers understand your changes as well as the purpose of your pull request.
  • Link your PR to any relevant issues it addresses.
  • Allow edits from maintainers so the branch can be updated for a merge. Once you submit your PR, a Docs team member will review your proposal. We may ask questions or request additional information.
  • Make sure you add an entry with your changes to the Changelog. Also make sure that it is in the appropriate section of the document.
  • We may ask for changes to be made before a PR can be merged, either using suggested changes or pull request comments. You can apply suggested changes directly through the UI. You can make any other changes in your fork, then commit them to your branch.
  • As you update your PR and apply changes, mark each conversation as resolved.
  • Resolve merge conflicts if they arise, using resources like this git tutorial for help.

Your PR is Merged!

Congratulations! The esp-rs team thanks you for your contributions!

Contributing to open source extends beyond just code! Each contribution, regardless of size, plays a significant role. We appreciate your involvement in this collective endeavor.