Skip to content

Commit

Permalink
Adjusting CONTRIBUTING.md to changes in driver
Browse files Browse the repository at this point in the history
  • Loading branch information
@playfulFence
playfulFence committed Jul 8, 2024
1 parent 505e1ef commit 5e1c51c
Showing 1 changed file with 29 additions and 20 deletions.
49 changes: 29 additions & 20 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,7 @@ Thank you for considering contributing to our project! Your efforts help make `e

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

# Quick Navigation

## Quick Navigation
* [New Contributor Guide]
* [Getting Started]
* [Issues: Reporting and Resolving]
Expand All @@ -25,7 +24,7 @@ This guide outlines the contribution workflow, from reporting issues and submitt
[Pull Request: From Submission to Merge]: #pull-request-from-submission-to-merge
[Your PR is merged!]: #your-pr-is-merged

# New Contributor Guide
## New Contributor Guide

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

Expand All @@ -35,17 +34,16 @@ Welcome aboard! If you're new to `esp-hal` or open-source contribution, here are
* Workflow Insights: [GitHub Flow]
* Collaborating via [Pull Requests]

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

[Understanding the Project]: README.md
[GitHub's Guide]: https://docs.github.com/en/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github
[Setting Up Git]: https://docs.github.com/en/get-started/quickstart/set-up-git
[GitHub Flow]: https://docs.github.com/en/get-started/quickstart/github-flow
[Pull Requests]: https://docs.github.com/en/github/collaborating-with-pull-requests
[esp-rs API guidelines]: ./API-GUIDELINES.md

Before adding or changing code you might want to review the [esp-rs API guidelines](./API-GUIDELINES.md)

# Getting Started

### Issues
## Getting Started

### Issues: Reporting and Resolving

Expand All @@ -62,30 +60,41 @@ Browse [existing issues] to find one that resonates with you. Use labels for eas

[existing issues]: https://github.com/esp-rs/esp-hal/issues

### Making Changes: Fork, Edit, and Pull Request
#### 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.
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.

[forking the repository]: https://docs.github.com/en/github/getting-started-with-github/fork-a-repo
[rustup.rs]: https://rustup.rs/

#### 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.

[HIL]: https://github.com/esp-rs/esp-hal/tree/main/hil-test

### 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.
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.

#### What You Should Do:
Further steps that can (or should) be taken in testing:

* **API changes**: If your contribution changes the API, please take care to adapt the driver and examples to these changes.
* **Run Related Examples**: After making changes, please run any examples that are affected by your contributions. This helps verify that not only do they build successfully, but they also perform as expected.
* **Manual Testing**: For hardware-related changes, manually test your changes on the actual devices when possible. If not - please write about it in the corresponding issue, someone from our team will definitely take the time to do it! This is crucial because hardware behavior can sometimes differ from what's simulated or expected.
* Using [xtask], build examples for the specified chip.
* Build the documentation if it has been modified using the `run-doc-test` command in [xtask].
* Run the [HIL] tests locally if changes have been made to them.

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
[xtask]: https://github.com/esp-rs/esp-hal/tree/main/xtask

### 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.
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.

```shell
rustup component add rustfmt
Expand Down Expand Up @@ -113,7 +122,7 @@ This will use `rustfmt` to ensure that all source code is formatted correctly pr

[Link your PR]: https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue
[Allow edits from maintainers]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-forkmember
[change log]: esp-hal/CHANGELOG.md
[Changelog]: esp-hal/CHANGELOG.md
[suggested changes]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request
[resolved]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request#resolving-conversations
[this git tutorial]: https://github.com/skills/resolve-merge-conflicts
Expand Down

0 comments on commit 5e1c51c

Please sign in to comment.