Skip to content

Contributing

Jump to bottom
Abdelkader Boudih edited this page Aug 24, 2026 · 2 revisions

Contributing

ChaosBSD accepts incomplete work. That's the point.

Why Crowdsourcing Matters

Hardware lies. Specs lie. Assumptions kill drivers.

A real example: An Apple driver had a hardcoded registry lock: 100 => 256. One Mac had 27x registries. Another had 29x. The obvious fix? Bump the number to 300 and submit.

That fix was wrong.

The actual solution: read the registry count dynamically, then expose it. A MacBook Pro has 786 registries. No hardcoded constant would have survived.

This is why ChaosBSD exists. One person cannot test every device. Devices vary within the same model. A single hardware revision changes behavior. A firmware update shifts register layouts. You cannot assume. You must test.

If you "vibe code" a driver and submit, you will be blocked. Drivers require evidence from real hardware.

Code of Submission

1. Ship It

If your driver compiles, attaches, and does something useful without panicking, submit it. Don't wait for perfection. Waiting is how driver work dies in personal branches.

2. Small Is Valid

One PCI ID tested. One quirk added. One firmware version documented. These are real contributions. Submit them.

3. No Assumptions

Hardcoded values must be justified. Magic numbers must be explained. If you don't know why something works, say so. Someone with different hardware will find out.

4. Document What You Tested

Your code doesn't need to be complete, but your test context does:

  • Exact hardware model and revision
  • Firmware version
  • BIOS version
  • What worked, what didn't, what you didn't test

5. Credit Survives Chaos

History resets. Commits get squashed. But when a driver graduates to FreeBSD, every contributor gets co-authorship in the upstream commit. Your one-line fix is credited alongside the initial implementation.

6. Don't Break the Build

The bar is low, but it exists. Code must compile against FreeBSD 16-CURRENT. If it doesn't build, it doesn't merge.

7. No Unmarked Binaries

Firmware blobs are allowed but must document:

  • Source - where it came from
  • License - or explicit acknowledgment of none

No exceptions.

System Requirements

Keep your system updated.

We expect:

  • Latest BIOS
  • Latest firmware

Exception: if the vendor's latest version adds lock-in or telemetry, stay on the last clean version and document why.

Upgrading is easier than backward compatibility. We don't chase old firmware bugs.

What to Submit

Drivers that work (even partially):

  • Attaches but doesn't fully function? Submit.
  • Works on one device but not others? Submit.
  • Handles basic ops but crashes on edge cases? Submit.

Test results:

  • PCI/USB IDs you've validated
  • Firmware versions that work (or don't)
  • Panic logs, backtraces, dmesg output
  • "When I do X, Y happens" reports

Fixes and quirks:

  • One-line fixes count
  • Device-specific workarounds count
  • Documentation updates count

How to Submit

  1. Fork ChaosBSD
  2. Branch from unstable
  3. Commit with clear messages (what changed, what hardware, what works)
  4. Open a PR - describe what you tested and how

PRs are merged fast. The goal is iteration, not gatekeeping.

What Happens After

Your code lives in ChaosBSD until:

  • It graduates to FreeBSD (GPL portions extracted to ports first)
  • A reset occurs (code is reapplied from the patch set)
  • Someone improves on it (collaborative development)

History is disposable. Credit is not.

Don't Know Where to Start?

  • Pick a device you own that doesn't work on FreeBSD
  • Check if anyone's started work on it
  • Try to attach it, document what happens
  • Submit whatever you learn

Driver development is hard. You don't need to finish but you need to start.

Clone this wiki locally