Skip to content

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
State machine of a driver request with the stages Requested, Triaged, Datasheet acquired, In design, Building, In review and Released, and a Declined end state.State machine of a driver request with the stages Requested, Triaged, Datasheet acquired, In design, Building, In review and Released, and a Declined end state.
From a request to a release candidate
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

  1. Fork the repository and create a branch.
  2. Make the change, with its docs and tests in the same pull request.
  3. Sign off every commit: git commit -s. CI fails a pull request with a commit that has no matching Signed-off-by: line.
  4. Open the pull request. CI gate runs 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.