CONTRIBUTING.md

# Contributing to Pigweed

Pigweed lets anyone contribute to the project, regardless of their employer. The
Pigweed project reviews and encourages well-tested, high-quality contributions
from anyone who wants to contribute to Pigweed.

## Contributor License Agreement

Contributions to this project must be accompanied by a Contributor License
Agreement (CLA).

To see any Contributor License Agreements on file or to sign a CLA, go to
<https://cla.developers.google.com/>.

For more information about the Google CLA, see
[Contributor License Agreements](https://cla.developers.google.com/about).

## Contributing changes and submitting code reviews

All changes require review, including changes by project members.

For detailed instructions on how to contribute changes, see
[the Gerrit docs](https://gerrit-review.googlesource.com/Documentation/intro-user.html).

## Community guidelines

This project observes the following community guidelines:

*   [Google's Open Source Community Guidelines](https://opensource.google/conduct/)

## Required presumit testing

We don’t have hardware-in-the-loop testing yet, so the following manual testing
is needed before merging *any* change to this repo.

### Checklist for new code

-   [ ] New binaries or tests?
    -   [ ] Update `//BUILD.bazel` with updated deps on
        `:refresh_compile_commands`.
    -   [ ] Update `//.bazelrc` presubmit section with the new binaries you want
        built in CQ after the line `build:presubmit -- \ `
-   [ ] New protos?
    -   [ ] Update `//tools/airmaranth/device.py` with the proto imports under
        `get_all_protos()`.
    -   [ ] Add the proto deps to `:airmaranth_lib` in `//tools/BUILD.bazel`
-   [ ] Run the regression suite (below) manually

### Regression testing suite: manual testing steps

For now, assumes you have
[a full setup](https://pigweed.dev/docs/showcases/sense/tutorial/flash.html#option-full-setup):

*   Pico RP2040
*   Enviro+ pack
*   OmniBus extender
*   Debug probe

#### Host simulator

##### Steps

1.  In terminal 1: Run simulator `$ bazelisk run //apps/blinky:simulator_blinky`
1.  In terminal 2:

    *   Run console `$ bazelisk run //apps/blinky:simulator_console`
    *   In the console, run: `>>>
        device.rpcs.pw.rpc.EchoService.Echo(msg='hello')`

##### Expected result

Return value shown in console is: `(Status.OK, pw.rpc.EchoMessage(msg=’hello’))`

#### On-device RP2040 apps

##### Flashing test

###### Steps

In a terminal (or in VSCode by “Run target”):

*   `$ bazelisk run //apps/blinky:flash`
*   `$ bazelisk run //apps/blinky:rp2040_console`

###### Expected result

1.  Successful build, flash, and console loads.
1.  RP2040 LED toggles @ 1Hz
1.  Log panel displays: `RpcDevice BLINKY Toggling Led`

##### RPC test

###### Steps

In the console, run: `>>> device.rpcs.pw.rpc.EchoService.Echo(msg='hello')`

###### Expected result

Return value shown in console is: `(Status.OK, pw.rpc.EchoMessage(msg=’hello’))`

##### Toggle blinky test

1.  Close any active consoles. Run `$ bazelisk run
    //apps/blinky:rp2040_toggle_blinky`. The Pico LED should *stop* blinking.
1.  Run `$ bazelisk run //apps/blinky:rp2040_toggle_blinky` again. The Pico LED
    should *start* blinking.

#### On-device RP2040 tests

##### Steps

1.  In terminal 1: Start test runner: `$ bazelisk run \
    @pigweed//targets/rp2040/py:unit_test_server \ -- --debug-probe-only`
1.  In terminal 2: Run tests: `$ bazelisk test --config=rp2040 //...`

##### Expected result

Test runner successfully connects to the device. Tests run and pass.