Contributing¶
Good first contributions¶
| You can | Where |
|---|---|
| Fix a doc, a typo or a broken example | Any repository; the docs live in docs/ |
| Ask for a driver, or say which chip you need most | Request a driver |
| Add a vote to a request you also need | A thumbs-up reaction on that request's issue |
| Run a driver on a real chip and report what you saw | The driver's repository; see hardware validation |
| Report that a chip does not do what its datasheet says | The datasheet erratum form |
| Write a driver for a chip you know | Start from driver-template and open a discussion first |
| Ask for a port to an MCU family, SDK or RTOS | The port request form |
| Report a bug | The repository's issues, with the bug form |
Issues labelled good first issue are a good start.
Request a driver¶
A driver is written only from public documents, so a request is a form with a link. Search the open and closed requests first; if the chip is already there, add a thumbs-up reaction. That is the vote.
| I want to | Open |
|---|---|
| A driver for a chip that has none | Request a driver |
| The drivers on an MCU family, SDK or RTOS without a port | Request a port or target |
| Report a datasheet erratum | Datasheet erratum |
Figure description and sources
A request opens as Requested and becomes Triaged once a maintainer has found the part clear, not a duplicate and within scope. Datasheet acquired follows when the public documents cover the whole chip, then In design while the architecture note is written, Building while the driver, its tests and its docs are written, In review for the independent rounds and the local rehearsal of CI, and Released when a release candidate is out. A request that will not be done is Declined, with the reason in a comment.
Drawn from: docs/model/request-pipeline.state.yml.
Every request sits on the Driver pipeline board of the drivers organisation, and its Stage shows where it is.
When you open or edit a request, a triage workflow reads your part number, labels the issue chip:<PART>, lists
duplicates and existing drivers that may cover the part, and labels needs-datasheet or needs-info when something
is missing. Editing the issue runs the check again.
The datasheet link must be an https link on the chip vendor's own website, reachable without an account, and a
link, never an attachment. Never link a document under NDA.
The queue is ordered by votes, how complete the public documents are, effort (simpler chips go first) and help offered: someone who can test on hardware or review moves a request up. A request may be declined when the documents are not public, the part is obsolete, or it is a module whose firmware already hides the chip. The reason is always given in a comment. The request repository has every detail.
How a change gets in¶
- Fork the repository and create a branch.
- Make the change, with its docs and tests in the same pull request.
- Sign off every commit:
git commit -s. CI fails a pull request with a commit that has no matchingSigned-off-by:line. - Open the pull request.
CI gateruns every check and tells you what is missing; a maintainer reviews.
Workflows from a first-time contributor's fork wait for a maintainer's approval before they run. If a change affects behaviour on hardware, say in the pull request which MCU and board you ran it on and what you observed, or write "not verified on hardware" with the steps someone should run.
Security¶
Report a vulnerability privately through the repository's Security tab ("Report a vulnerability"), never in a public issue. The security policy says what happens next.
Community¶
Be kind and specific: the code of conduct applies everywhere. Full details are in the contributing guide. Questions and ideas go to Discussions; anything else to kokeblabs@gmail.com.