@@ -4,4 +4,201 @@ Guideline to contribute to this package
44
55---------------
66
7- ## TBD
7+ ## General
8+
9+ You're welcome to contribute to this package with or without raising an issue
10+ before creating a PR.
11+
12+ Please follow the following guideline covering all necessary steps and hints
13+ for a smooth review and contribution process.
14+
15+ ## Code
16+
17+ To test and verify your changes it is recommended to run all checks locally in
18+ a virtual environment. Use the following command to setup and install all
19+ tools.
20+
21+ ``` bash
22+ python3 -m venv .venv
23+ source .venv/bin/activate
24+
25+ pip install -r requirements-test.txt
26+ ```
27+
28+ For very old systems it might be necessary to use an older version of
29+ ` pre-commit ` , an "always" working version is ` 1.18.3 ` with the drawback of not
30+ having ` flake8 ` and maybe other checks in place.
31+
32+ ### Format
33+
34+ The Python code format is checked by ` flake8 ` with the default line length
35+ limit of 79. Further configuration can be found in the ` .flake8 ` file in the
36+ repo root.
37+
38+ The YAML code format is checked by ` yamllint ` with some small adjustments as
39+ defined in the ` .yamllint ` file in the repo root.
40+
41+ Use the following commands (inside the virtual environment) to run the Python
42+ and YAML checks
43+
44+ ``` bash
45+ # check Python
46+ flake8 .
47+
48+ # check YAML
49+ yamllint .
50+ ```
51+
52+ ### Tests
53+
54+ Every code should be covered by a unittest. This can be achieved for
55+ MicroPython up to some degree, as hardware specific stuff can't be always
56+ tested by a unittest.
57+
58+ For now ` nose2 ` is used as tool of choice. The configuration is defined in the
59+ ` tests/unittest.cfg ` file.
60+
61+ All reports are placed inside the ` reports ` folder or a subfolder of it. It
62+ can be created with
63+
64+ ``` bash
65+ python create_report_dirs.py
66+ ```
67+
68+ After this either all or a specific unittest can be executed, see the following
69+ commands as an example
70+
71+ ``` bash
72+ # run all tests
73+ nose2 --config tests/unittest.cfg
74+
75+ # run only one specific tests
76+ nose2 tests.test_blink.TestBlink.test_flash_led
77+ ```
78+
79+ As last step the coverage report can be generated. There might be a minimum
80+ coverage limit set up for the project. Check the value of ` target ` in the
81+ ` codecov.yaml ` file, located in the repo root.
82+
83+ ``` bash
84+ coverage html
85+ ```
86+
87+ The coverage report is placed at ` reports/coverage/html/index.html `
88+
89+ ### Precommit hooks
90+
91+ This repo is equipped with a ` .pre-commit-config.yaml ` file to combine most of
92+ the previously mentioned checks plus the changelog validation, see next
93+ section, into one handy command. It additionally allows to automatically run
94+ the checks on every commit.
95+
96+ In order to run this repo's pre commit hooks, perform the following steps
97+
98+ ``` bash
99+ # install pre-commit to run before each commit, optionally
100+ pre-commit install
101+
102+ pre-commit run --all-files
103+ ```
104+
105+ ## Changelog
106+
107+ The changelog format is based on [ Keep a Changelog] [ ref-keep-a-changelog ] , and
108+ this project adheres to [ Semantic Versioning] [ ref-semantic-versioning ] .
109+
110+ Please add a changelog entry for every PR you contribute. The versions are
111+ seperated into ` MAJOR.MINOR.PATCH ` :
112+
113+ - Increment the major version by 1 in case you created a breaking, non
114+ backwards compatible change which requires the user to perform additional
115+ tasks, adopt his currently running code or in general can't be used as is anymore.
116+ - Increment the minor version by 1 on new "features" which can be used or are
117+ optional, but in either case do not require any changes by the user to keep
118+ the system running after upgrading.
119+ - Increment the patch version by 1 on bugfixes which fix an issue but can be
120+ used out of the box, like features, without any changes by the user. In some
121+ cases bugfixes can be breaking changes of course.
122+
123+ Please add the date the change has been made as well to the changelog
124+ following the format ` ## [MAJOR.MINOR.PATCH] - YYYY-MM-DD ` . It is not
125+ necessary to keep this date up to date, it is just used as meta data.
126+
127+ The changelog entry shall be short but meaningful and can of course contain
128+ links and references to other issues or PRs. New lines are only allowed for a
129+ new bulletpoint entry. Usage examples or other code snippets should be placed
130+ in the code documentation, README or the docs folder.
131+
132+ ### General
133+
134+ The package version file, located at ` <PACKAGE_NAME>/version.py ` contains the
135+ latest changelog version.
136+
137+ To avoid a manual sync of the changelog version and the package version file
138+ content, the ` changelog2version ` package is used. It parses the changelog,
139+ extracts the latest version and updates the version file.
140+
141+ The package version file can be generated with the following command consuming
142+ the latest changelog entry
143+
144+ ``` bash
145+ changelog2version \
146+ --changelog_file changelog.md \
147+ --version_file < PACKAGE_NAME> /version.py \
148+ --version_file_type py \
149+ --debug
150+ ```
151+
152+ To validate the existing package version file against the latest changelog
153+ entry use this command
154+
155+ ``` bash
156+ changelog2version \
157+ --changelog_file=changelog.md \
158+ --version_file=< PACKAGE_NAME> /version.py \
159+ --validate
160+ ```
161+
162+ ### MicroPython
163+
164+ On MicroPython the ` mip ` package is used to install packages instead of ` pip `
165+ at MicroPython version 1.20.0 and newer. This utilizes a ` package.json ` file
166+ in the repo root to define all files and dependencies of a package to be
167+ downloaded by [ ` mip ` ] [ ref-mip-docs ] .
168+
169+ To avoid a manual sync of the changelog version and the MicroPython package
170+ file content, the ` setup2upypackage ` package is used. It parses the changelog,
171+ extracts the latest version and updates the package file version entry. It
172+ additionally parses the ` setup.py ` file and adds entries for all files
173+ contained in the package to the ` urls ` section and all other external
174+ dependencies to the ` deps ` section.
175+
176+ The MicroPython package file can be generated with the following command based
177+ on the latest changelog entry and ` setup ` file.
178+
179+ ``` bash
180+ upy-package \
181+ --setup_file setup.py \
182+ --package_changelog_file changelog.md \
183+ --package_file package.json
184+ ```
185+
186+ To validate the existing package file against the latest changelog entry and
187+ setup file content use this command
188+
189+ ``` bash
190+ upy-package \
191+ --setup_file setup.py \
192+ --package_changelog_file changelog.md \
193+ --package_file package.json \
194+ --validate
195+ ```
196+
197+ ## Documentation
198+
199+ Please check the ` docs/DOCUMENTATION.md ` file for further details.
200+
201+ <!-- Links -->
202+ [ ref-keep-a-changelog ] : https://keepachangelog.com/en/1.0.0/
203+ [ ref-semantic-versioning ] : https://semver.org/spec/v2.0.0.html
204+ [ ref-mip-docs ] : https://docs.micropython.org/en/v1.20.0/reference/packages.html
0 commit comments