# Contributing to Free Humanoid Centaur Thank you for considering a contribution. This morphology is open hardware, open firmware, open data, and is governed by the same defensive-publication discipline as its siblings [Free Humanoid Platform](../free-humanoid-platform/CONTRIBUTING.md) (bipedal) and [Free Humanoid Wheeled](../free-humanoid-wheeled/CONTRIBUTING.md) (wheeled). This document is the contract. **The contributor norms are inherited verbatim from the bipedal sibling**; the differences are highlighted below. If anything in this document is unclear, the canonical statement is in [free-humanoid-platform/CONTRIBUTING.md](../free-humanoid-platform/CONTRIBUTING.md). --- ## Quality bar A contribution is acceptable for merge when: 1. **Every load-bearing design choice cites a [Free Humanoid Corpus](https://github.com/openIE-dev/free-humanoid-corpus) entry by id.** "Load-bearing" means: any choice that changes the descriptor, the BOM, the firmware HAL, the safety supervisor's invariants, the policy architecture, the quadruped-base topology, the wheel-leg-hybrid foot, the dual-mode locomotion controller, the shoal dock-A protocol surface, or the comms protocol. Cosmetic changes do not require corpus citation. 2. **The cited entry actually anticipates the choice.** Same standard as the siblings. 3. **The commit message names the corpus entry id.** A commit that adds a new quadruped-base subsystem element reads `[base] add foot IP67 seal; cite anymal-d-eth-rsl-2022` rather than `[base] update electronics`. 4. **Documentation updates are part of the same commit.** [ARCHITECTURE.md](ARCHITECTURE.md), [prior-art/INDEX.md](prior-art/INDEX.md), and any subdirectory README that depends on the choice are updated together. 5. **Hardware contributions include an open-tooling buildability check.** Mechanical CAD must be readable in FreeCAD or OpenSCAD. PCB layouts must be readable in KiCad. Firmware must build with open toolchains. 6. **Safety-relevant contributions go through review by the safety supervisor maintainer.** Same posture as the siblings. The quadruped-base-specific invariants (slope tilt 30°, foot-fall validation, balance-margin hard-stop, leg-collision avoidance, mode-transition gate) are subject to additional scrutiny because they are new to this morphology and the mode-transition gate is new architecture. 7. **Mission-integration contributions go through review by the shoal maintainer.** Any change to the dock-A cartridge-swap protocol, waste-hopper retrieval interface, or biology-reservoir handshake requires sign-off from the shoal architecture maintainer in addition to the centaur-platform maintainer. 8. **Wheel-leg-hybrid foot contributions go through review by both the base-subsystem maintainer and the safety supervisor maintainer.** The mode-transition mechanism is jointly mechanical and safety-critical — both maintainers approve. --- ## Defensive publication norms Inherited from the bipedal sibling. Every commit is a public disclosure that, taken with its commit timestamp, becomes citeable as 102/103 prior art on the date of disclosure. - **Don't strip rationale.** - **Cite primary sources.** - **Mark drafts as drafts.** --- ## No-patent-aggression contributor norm Inherited from the bipedal sibling. By contributing, you agree that you will not assert any patent against this morphology, its derivatives, its users, its forks, or any other contributor, in connection with any matter covered by the design, BOM, firmware, descriptors, or documentation. --- ## Reference-design-not-product Inherited. There is no warranty, no support contract, no service tier, no SLA, no certified configuration. Forks are encouraged. If you are deploying the platform in a safety-critical environment — and a wetland or post-disaster-zone deployment *is* safety-critical — you are responsible for the safety case. The contributor base provides the architecture (see ARCHITECTURE §2.6) but cannot certify any specific deployment satisfies any specific regulatory regime. --- ## Pull request checklist Before opening a PR: - [ ] Every load-bearing design choice cites at least one corpus entry id. - [ ] The cited entry actually anticipates the choice. - [ ] Commit messages name the corpus entry id where applicable. - [ ] Documentation (README, ARCHITECTURE, prior-art/INDEX, subdirectory READMEs) updated. - [ ] Open-tooling buildability check passes for any hardware artifact. - [ ] Safety-relevant changes flagged for safety-maintainer review. - [ ] Mission-integration changes flagged for shoal-maintainer review. - [ ] Wheel-leg-hybrid foot changes flagged for both base-maintainer and safety-maintainer review. - [ ] Drafts marked as drafts. - [ ] Contributor agrees to the no-patent-aggression norm. --- ## Reporting security or safety issues For safety-critical issues — supervisor bypass, fail-safe failure modes, undocumented deadlocks, mode-transition invariant escapes, foot-fall-validation invariant failures, slope-tilt latch failures — please email the safety maintainer directly rather than opening a public issue, until the fix is in. For non-safety security issues, open a regular issue. --- ## Style guide for documentation Inherited from the bipedal sibling. - Prose, not bullets, where the content is argued. Bullets where it is enumerated. - Cite corpus entries inline as `` `entry-id` `` (backticks). - Use markdown link syntax for cross-references. - Architecture decisions: argued prose, with options, recommendation, and TBD callout where the user (David) needs to make the call. - Subsystem READMEs: scoped to the concern, no architectural argument. Architectural argument lives in [ARCHITECTURE.md](ARCHITECTURE.md). --- ## Maintainer approval Maintainership is currently held by the OpenIE / Free Humanoid project lead (David Charlot). Component-area maintainers (base, upper-body, electronics, firmware, control, sim, safety supervisor, shoal-integration) are appointed as the project grows. The wheel-leg-hybrid foot subsystem and the mode-transition supervisor invariant are flagged as "needs a dedicated maintainer at Phase 2" given their cross-cutting nature.