22
33First of all, thanks for contributing!
44
5- This document provides some basic guidelines for contributing to this repository. To propose
6- improvements or fix a bug, feel free to submit a PR.
5+ This document provides some basic guidelines for contributing to this
6+ repository. To propose improvements or fix a bug, feel free to submit a PR.
77
88## Legal requirements
99
1010Before we can accept your contributions you have to sign the [ Contributor License Agreement] [ 0 ]
1111
1212## Prerequisites
1313
14- To build the Arduino CLI from sources you need the following tools to be available in your local
15- enviroment:
14+ To build the Arduino CLI from sources you need the following tools to be
15+ available in your local enviroment:
1616
1717* [ Go] [ 1 ] version 1.12 or later
1818* [ Taskfile] [ 2 ] to help you run the most common tasks from the command line
@@ -30,73 +30,81 @@ From the project folder root, just run:
3030task build
3131```
3232
33- The project uses Go modules so dependencies will be downloaded automatically, you should end with
34- an ` arduino-cli ` executable in the same folder.
33+ The project uses Go modules so dependencies will be downloaded automatically;
34+ at the end of the build, you should find an ` arduino-cli ` executable in the
35+ same folder.
3536
3637## Running the tests
3738
38- There are several checks and test suites in place to ensure the code works as expected but also it
39- is written in a way that's consistent across the whole codebase. Such tests can be run one after
40- another by running the command:
39+ There are several checks and test suites in place to ensure the code works as
40+ expected but it's also written in a way that's consistent across the whole
41+ codebase. To avoid pushing changes that will cause the CI system to fail, you
42+ can run most of the tests locally.
43+ 44+ To ensure code style is consistent, run:
4145
4246``` shell
43- task test
47+ task check
4448```
4549
46- If you want to only run unit tests and skip other checks, you can run :
50+ To run unit tests:
4751
4852``` shell
4953task test-unit
5054```
5155
52- Similarly, if you're only interested in running integration tests, you can do (be sure to read the
53- part dedicated to integration tests if something doesn't work ):
56+ To run integration tests (these will take some time and require special setup,
57+ see following paragraph ):
5458
5559``` shell
5660task test-integration
5761```
5862
5963### Integration tests
6064
61- Being a command line interface, Arduino CLI is heavily interactive and it has to stay consistent
62- in accepting the user input and providing the expected output and proper exit codes. On top of this,
63- many Arduino CLI features involve communicating with external devices, most likely through a serial
65+ Being a command line interface, Arduino CLI is heavily interactive and it has to
66+ stay consistent in accepting the user input and providing the expected output
67+ and proper exit codes. On top of this, many Arduino CLI features involve
68+ communicating with external devices, most likely through a serial
6469port, so unit tests can only put our confidence that the code is working so far.
6570
66- For these reasons, in addition to regular unit tests the project has a suite of integration tests
67- that actually run Arduino CLI in a different process and assess the options are correctly
68- understood and the output is what we expect.
71+ For these reasons, in addition to regular unit tests the project has a suite of
72+ integration tests that actually run Arduino CLI in a different process and
73+ assess the options are correctly understood and the output is what we expect.
6974
70- To run the full suite of integration tests you need an Arduino device attached to a serial port and
71- a working Python environment. Chances are that you already have Python installed in your system, if
72- this is not the case you can [ download ] [ 3 ] the official distribution or use the package manager
73- provided by your Operating System.
75+ To run the full suite of integration tests you need an Arduino device attached
76+ to a serial port and a working Python environment. Chances are that you already
77+ have Python installed in your system, if this is not the case you can
78+ [ download ] [ 3 ] the official distribution or use the package manager provided by your Operating System.
7479
75- Some dependencies need to be installed before running the tests and to avoid polluting your global
76- Python enviroment with dependencies that might be only used by the Arduino CLI, you can use a
77- [ virtual environment] [ 4 ] . There are many ways to manage virtual environments, for example you can
78- use a productivity tool called [ hatch] [ 5 ] . First you need to install it (you might need to ` sudo `
80+ Some dependencies need to be installed before running the tests and to avoid
81+ polluting your global Python enviroment with dependencies that might be only
82+ used by the Arduino CLI, you can use a [ virtual environment] [ 4 ] . There are many
83+ ways to manage virtual environments, for example you can use a productivity tool
84+ called [ hatch] [ 5 ] . First you need to install it (you might need to ` sudo `
7985the following command):
8086
8187``` shell
8288pip3 install --user hatch
8389```
8490
85- Then you can create a virtual environment to be used while working on Arduino CLI:
91+ Then you can create a virtual environment to be used while working on Arduino
92+ CLI:
8693
8794``` shell
8895hatch env arduino-cli
8996```
9097
91- At this point the virtual environment was created and you need to make it active every time you
92- open a new terminal session with the following command:
98+ At this point the virtual environment was created and you need to make it active
99+ every time you open a new terminal session with the following command:
93100
94101``` shell
95102hatch shell arduino-cli
96103```
97104
98- From now on, every package installed by Python will be confined to the ` arduino-cli ` virtual
99- environment, so you can proceed installing the dependencies required with:
105+ From now on, every package installed by Python will be confined to the
106+ ` arduino-cli ` virtual environment, so you can proceed installing the
107+ dependencies required with:
100108
101109``` shell
102110pip install -r test/requirements.txt
@@ -110,29 +118,33 @@ task test-integration
110118
111119## Pull Requests
112120
113- In order to ease code reviews and have your contributions merged faster, here is a list of items
114- you can check before submitting a PR:
121+ In order to ease code reviews and have your contributions merged faster, here is
122+ a list of items you can check before submitting a PR:
115123
116124* Create small PRs that are narrowly focused on addressing a single concern.
117- * PR titles indirectly become part of the CHANGELOG so it's crucial to provide a good
118- record of ** what** change is being made in the title; ** why** it was made will go in the
119- PR description, along with a link to a GitHub issue if it exists.
125+ * PR titles indirectly become part of the CHANGELOG so it's crucial to provide a
126+ good record of ** what** change is being made in the title; ** why** it was made
127+ will go in the PR description, along with a link to a GitHub issue if it
128+ exists.
120129* Write tests for the code you wrote.
121130* Open your PR against the ` master ` branch.
122131* Maintain ** clean commit history** and use ** meaningful commit messages** .
123- PRs with messy commit history are difficult to review and require a lot of work to be merged.
124- * Your PR must pass all CI tests before we will merge it. If you're seeing an error and don't think
125- it's your fault, it may not be! The reviewer will help you if there are test failures that seem
132+ PRs with messy commit history are difficult to review and require a lot of
133+ work to be merged.
134+ * Your PR must pass all CI tests before we will merge it. If you're seeing an error and don't think
135+ it's your fault, it may not be! The reviewer will help you if there are test
136+ failures that seem
126137 not related to the change you are making.
127138
128139## Additional settings
129140
130- If you need to push a commit that's only shipping documentation changes or example files, thus a
131- complete no-op for the test suite, please start the commit message with the string ** [ skip ci] **
132- to skip the build and give that slot to someone else who does need it.
141+ If you need to push a commit that's only shipping documentation changes or
142+ example files, thus a complete no-op for the test suite, please start the commit
143+ message with the string ** [ skip ci] ** to skip the build and give that slot to
144+ someone else who does need it.
133145
134- If your PR doesn't need to be included in the changelog, please start the PR title with the string
135- ** [ skip changelog] **
146+ If your PR doesn't need to be included in the changelog, please start the PR
147+ title with the string ** [ skip changelog] **
136148
137149[ 0 ] : https://cla-assistant.io/arduino/arduino-cli
138150[ 1 ] : https://golang.org/doc/install
0 commit comments