Thank you for helping improve OpenHornet. This guide explains how to report problems, propose improvements, select work, and contribute changes to the OpenHornet baseline.

• Reporting Problems and Proposing Changes
  • Choose the Correct Issue Type
  • Baseline Builds and Modifications
  • How to Report an Issue
  • What a Good Issue Looks Like
  • What to Avoid
  • Examples of Good Issues
• Contributing to the OpenHornet Baseline
  • What Is an OpenHornet Contribution?
  • Where Can I Find Work?
  • What Commitment Is Required?
• Processes
  • MCAD Revision Process
  • ECAD Revision Process
• Required Software
  • General
  • MCAD
  • ECAD
    • KiCad 10 symbol library setup
• GitHub Operations and Standards
  • How to Create a Pull Request
  • Updating an Existing Pull Request
• Repository Structure
  • Branches
  • Branch Types
  • Branch Naming
  • Pull Request Targets
  • Keeping Branches Current
• Merge Expectations
  • Releases
  • Why OpenHornet Uses This Strategy
• Commit Standards
  • Commit Frequency
  • Commit Messages
• Important Links

If you find a problem, have an idea that would make something easier or function better, or want to propose new functionality, please create a GitHub issue.

You are welcome to discuss the subject on Discord first, especially if you are unsure whether the behavior is expected. However, work that may affect the OpenHornet baseline must be tracked in GitHub. Discord conversations are not a substitute for an issue because they are difficult to search, organize, assign, and associate with pull requests.

Do not be intimidated by the issue forms. Provide the information you know, state clearly when something is unknown, and ask for help on Discord when necessary. Issues can be edited as more information becomes available.

Issue type describes the purpose of the work. Repository category describes where the work occurs.

OpenHornet uses four primary issue types:

Use a Bug report when something in the current OpenHornet design, documentation, manufacturing package, or baseline build is incorrect or broken.

Examples include:

• Incorrect dimensions or mounting geometry
• A PCB connection or footprint error
• A drawing that disagrees with the model
• A manufacturing package that cannot be produced as intended
• A baseline component that does not fit or operate as specified

Use an Enhancement request to propose a new capability or an intentional change to the current design.

Examples include:

• Adding a new feature
• Improving fidelity
• Making an assembly easier or less expensive to build
• Proposing a new design approach
• Adding an optional supported configuration

Use an Obsolescence report when a purchased component is unavailable, discontinued, end-of-life, or requires a supply-driven replacement.

Examples include:

• A specified switch is no longer manufactured
• An IC is end-of-life
• A supplier permanently discontinued a specified part
• The original component has been replaced by a newer revision
• No legitimate distributor has stock of the specified component

An Obsolescence report should identify the exact manufacturer and part number, provide availability or lifecycle evidence, and list candidate replacements when known.

Use a Maintenance issue when the desired design already exists, but repository artifacts must be synchronized, migrated, cleaned up, consolidated, regenerated, replaced, or standardized.

Examples include:

• Updating MCAD assemblies to use a newly approved PCB revision
• Updating interconnect symbols after a PCB interface changes
• Regenerating tracked manufacturing files
• Standardizing KiCad libraries
• Replacing obsolete references after the replacement design has already been approved
• Synchronizing drawings, BOMs, models, and release files

Maintenance differs from Enhancement because Maintenance does not define a new capability or design direction. It brings dependent repository artifacts into alignment with an already established design.

Select the category based on the affected repository area:

• MCAD / Mechanical — Mechanical models, assemblies, structure, panels, mechanisms, mounting, fit, and physical integration
• ECAD / Electrical — PCBs, schematics, KiCad libraries, interconnects, wiring, connectors, and electrical integration
• Artwork — Placards, decals, labels, data plates, and vector artwork
• Drawings / Documentation — Engineering drawings, instructions, specifications, and other documentation
• Repository / Tooling / CI — Repository organization, automation, validation tooling, and continuous integration
• Other — Work that genuinely does not fit another category

Issue type and category are independent. For example:

• Updating an old PCB model in Fusion is Type: Maintenance and Category: MCAD.
• Updating an OH_Interconnect block symbol is Type: Maintenance and Category: ECAD.
• Correcting an incorrect PCB connector pinout is Type: Bug and Category: ECAD.
• Proposing a new mechanism is Type: Enhancement and Category: MCAD.

Interconnect and wiring work falls under ECAD. Interconnect is not a separate category.

OpenHornet maintains the official baseline design. A reported problem should therefore apply to a part built to the applicable OpenHornet specifications or be demonstrably relevant to the baseline.

If your build deviates from the baseline, disclose every relevant deviation in the issue. A modification does not automatically make a report invalid, but the report must demonstrate that the same problem exists in, or directly affects, the OpenHornet baseline.

Community modifications are generally maintained by their respective authors rather than the OpenHornet contributor team. Report problems that only affect a modification to the modification’s author or repository.

Do not conceal a deviation because it appears trivial. The OpenHornet maintainers must determine whether it affects the validity, safety, fit, function, manufacturing, or qualification of the report.

1. Create a GitHub account if you do not already have one.
2. Visit the OpenHornet issue-form selection page.
3. Select Bug, Enhancement, Obsolescence, or Maintenance.
4. Complete the form with as much relevant information as possible.
5. Clearly identify anything that is unknown or has not been tested.
6. Submit the issue and respond to any follow-up questions.

A blank issue remains available for subjects that genuinely do not fit one of the four forms. When using it, provide enough context, scope, and acceptance information for another contributor to understand and act on the issue.

A good issue includes:

• A clear and specific summary
• The affected OpenHornet or COTS part numbers
• The affected files, assemblies, PCBs, drawings, or repository paths
• The applicable release or development branch
• The current behavior or repository state
• The expected or desired state
• Steps to reproduce or locate the problem, when applicable
• Relevant screenshots, photographs, diagrams, or annotated images
• Any build deviations
• Candidate solutions or replacements, when known
• Objective completion or acceptance criteria
• Links to related issues, pull requests, requirements, or discussions
• Confirmation that you searched for an existing issue on the same subject

Do not assume that maintainers already know which part, assembly, sheet, or file you mean. Be specific enough that someone unfamiliar with your build can locate and understand the issue.

Files may be attached directly to the issue. Fusion, KiCad, STEP, log, or other files may need to be placed in a ZIP archive before GitHub will accept them.

Avoid:

• Reporting a modification-specific problem as a baseline defect
• Failing to disclose changes from the OpenHornet baseline
• Reporting an ECAD problem without identifying relevant electrical modifications
• Creating a duplicate without checking existing issues
• Reporting only that something “does not work”
• Omitting the affected part, file, assembly, or PCB when it can reasonably be identified
• Treating a Discord discussion as a permanent substitute for a GitHub issue
• Presenting an untested assumption as confirmed behavior
• Presenting a proposed replacement as qualified before it has been reviewed and tested

It is acceptable not to know everything. Clearly separate confirmed facts, observations, assumptions, proposed solutions, and test results.

• Issue #1204 — Identifies an unavailable component, documents the exact part, and proposes a possible replacement.
• Issue #1191 — Clearly identifies and illustrates an affected area of the 3D model.

A contribution generally follows this process:

1. A contributor or small team selects an existing GitHub issue.
2. The requirements and intended outcome are confirmed with Noctum or the applicable domain lead.
3. The contributor creates a focused branch from the current master.
4. The contributor completes the applicable MCAD, ECAD, documentation, artwork, or repository process.
5. The contributor verifies the change and updates all affected artifacts.
6. The contributor opens a pull request targeting master.
7. Review comments and required changes are addressed on the same branch and pull request.
8. The pull request is approved and merged by an authorized repository maintainer.

If a contributor wants to deviate from agreed requirements, discuss the proposed deviation with Noctum or the applicable domain lead before proceeding.

A pull request should normally reference the issue it addresses. Use a closing keyword such as Closes #123 when merging the pull request should close the issue automatically.

The OpenHornet Hardware Project Board contains organized and prioritized work.

The first issues in each domain’s TODO column generally represent the current priorities. New contributors should consider issues labeled good first issue.

You can also browse the OpenHornet Issues page for the complete, unprioritized issue list.

Unless directed otherwise by a project maintainer:

1. Prioritize critical and high-priority issues.
2. Prioritize Bugs and Obsolescence that affect baseline buildability or safety.
3. Complete blocking Maintenance work needed to propagate approved designs.
4. Work on Enhancements after higher-priority corrective work is addressed.

Check whether an issue is already assigned or has active work before starting. Comment on the issue or ask in Discord if ownership is unclear.

OpenHornet requires a disciplined approach so the project can maintain consistent quality, but contributors volunteer their own time and may contribute as much or as little as they can.

Every useful contribution is appreciated. OpenHornet contributors have ranged from students and individuals with little prior experience to experienced design professionals from many industries.

Communication is more important than speed. If you begin work and later cannot continue, update the issue so another contributor can take over without duplicating effort.

• Complete the OpenHornet Contributor Application.
• Obtain access to the OpenHornet Fusion 360 repository from the project maintainers. Contact Noctum on Discord.
• Confirm the issue requirements and affected assemblies before beginning work.

• Complete the OpenHornet Contributor Application.
• Read the applicable requirements under ECAD/docs/requirements.
• Use KiCad 10, the project-supported major version.
• Configure and use the OpenHornet KiCad libraries. Map OH_Symbols, KiCadCustomLib, OH_Interconnect and OpenHornet to their respective ${KICAD_USER_OH_SYMBOLS}/<nickname>.kicad_symdir folders, using the canonical nicknames (including underscores). ABSIS and Arduino Pro Mini 5v remain packed libraries. See the setup and migration guide.
• Update shared libraries only when required and include all affected references in the same contribution.
• Confirm the issue requirements and affected PCBs, libraries, interconnect sheets, and outputs before beginning work.

Interconnects, wiring diagrams, and OH_Interconnect block symbols are part of the ECAD workflow.

• GitHub Desktop, or a Git command-line workflow if you are already comfortable using it

• Fusion 360
• Shaper Utilities

• KiCad 10
• OpenHornet KiCad configuration and library instructions

Before changing a PCB or schematic, review the applicable OpenHornet ECAD requirements and confirm that the local KiCad libraries resolve to the same repository checkout and revision being edited.

Windows shortcut: install KiCad 10, initialize its built-in symbol and footprint libraries, then close all KiCad applications. In your complete OpenHornet checkout, double-click utils/tools/ecad/Setup-OpenHornetKiCad.bat. The PowerShell setup utility configures all four paths (symbols, footprints, 3D models and drawing templates), registers all six shared symbol libraries and OH_Footprints, and repairs existing shared-library entries in project tables under ECAD. It preserves unrelated settings, backs up every changed file with a restore manifest, supports -WhatIf and makes no changes when setup already matches. Reopen KiCad after it reports success; no manual OpenHornet library registration is required. See the commands, preview mode, verification and backup/restore instructions. Project table repairs appear in git diff; review them before committing. Until PR #1285 is merged, use its library/oh-symbols-unpacked branch to obtain the utility and converted libraries.

Manual alternative: after pulling the library migration, set KICAD_USER_OH_SYMBOLS in Preferences → Configure Paths to the absolute path of ECAD/lib/OH_Symbols in your checkout, for example C:\GitHub\OpenHornet\ECAD\lib\OH_Symbols on Windows. Keep all OpenHornet path variables pointed at the same checkout and revision.

In Preferences → Manage Symbol Libraries, add or edit these rows using library format KiCad:

Register each .kicad_symdir folder as one library. The four converted packed originals have been removed; ABSIS and Arduino Pro Mini 5v remain packed. Contributors pulling this migration only need to update the mappings, not run the conversion again. Footprint, 3D-model and template mappings are unchanged.

Use the exact underscore nicknames OH_Symbols and OH_Interconnect. Check Project Specific Libraries for entries that override the global mappings. If a schematic contains a spaced nickname, correct its library reference through native KiCad symbol remapping; changing a library-table nickname alone does not rewrite schematic symbol IDs.

If a library is not found, check the expanded absolute path in the error and confirm that the converted folder exists in that checkout. Browse the library in Symbol Editor and try placing a symbol, then undo. Test Tools → Update Symbols from Library on a disposable project copy; an existing schematic can display its cached symbols even when the external library is unavailable.

See the setup, Windows conversion, verification and troubleshooting guide and ECAD preflight instructions. Symbol consolidation into OH_Symbols and the associated schematic library-ID remapping will be handled in a separate PR; OH_Interconnect remains separate.

Click Fork in the upper-right corner of the OpenHornet repository.

This creates a copy of the repository under your GitHub account.

1. Install and sign in to GitHub Desktop.
2. Select File → Clone Repository.
3. Select your OpenHornet fork.
4. Choose an empty local folder.
5. Click Clone.

The repository is several gigabytes, so the initial clone may take some time.

In GitHub Desktop, select Current branch, then select master.

Pull the latest changes before creating your contribution branch.

Select Current branch → New Branch and create a descriptive branch following the naming guidance below.

Create the branch from the current tip of master.

Make the required changes in the appropriate application.

Keep the contribution focused on the issue being addressed. Update every affected caller, model, assembly, drawing, PCB, library, BOM, interconnect, manufacturing output, test, and document required by the change.

Complete the applicable design, fit, electrical, manufacturing, documentation, and repository checks.

Document what was tested, what was not tested, and any remaining limitations. Do not treat a clean automated check as proof of physical qualification.

Return to GitHub Desktop and enter a clear commit subject and detailed description.

Commit in focused increments so the history provides useful review and rollback points.

Click Publish branch or Push origin to upload the branch to your GitHub fork.

1. Open your fork on GitHub.
2. Select Compare & pull request.
3. Confirm that the base repository is jrsteensen/OpenHornet.
4. Confirm that the base branch is master.
5. Enter a clear title and complete the pull-request template.
6. Explain what changed and why.
7. Link the applicable issue.
8. Include before-and-after screenshots where appropriate.
9. Describe validation and test results.
10. Complete the applicable checklist.
11. Leave Allow edits from maintainers enabled.
12. Select Create pull request.

If a reviewer requests changes, make the changes on the same local branch, commit them, and push the branch again.

The existing pull request updates automatically. Do not open another pull request unless a repository maintainer specifically requests one.

OpenHornet uses a trunk-based workflow with one primary long-lived branch representing the current project integration point.

The trunk is master.

master
├── feat/ejection-seat-9-0
├── fix/obsolete-potentiometer
├── docs/system-interconnect
└── chore/hardware-optimization

The master branch is the single long-lived integration branch.

All contribution branches are created from master and open pull requests back into master. The branch should remain healthy and reviewable.

Contributors must not commit directly to master unless they are authorized project maintainers performing approved administrative work.

There is no permanent develop branch.

All non-administrative work should occur on a short-lived branch created from the current tip of master.

Branches should be:

• Focused on a single change or tightly related group of changes
• Kept as small as practical
• Pushed regularly
• Updated when master changes materially
• Merged promptly after review
• Deleted after merge

Branch type describes the implementation work and does not have to match the issue type exactly.

• Feature (feat/) — New capabilities, new parts, new assemblies, or other additive changes
• Fix (fix/) — Corrections to hardware, documentation, manufacturing files, or other baseline artifacts
• Documentation (docs/) — Documentation-only changes that are not naturally bundled with other work
• Chore (chore/) — Cleanup, synchronization, migration, refactoring, file organization, naming consistency, regeneration, or other maintenance work

An Obsolescence issue may result in a fix/ branch when a component replacement changes the baseline. A Maintenance issue will often use a chore/ branch, but may use another prefix when that better describes the implementation.

Use lowercase letters, numbers, and hyphens. The preferred format is:

type/short-description

Examples:

• feat/right-console-panel-update
• fix/obsolete-potentiometer
• fix/standby-altimeter-clearance
• docs/jlcpcb-package-guide
• chore/update-absis-models
• chore/normalize-file-names

Avoid vague names such as:

• johns-branch
• stuff
• new-update
• test

All normal pull requests must target master.

A pull request should be small enough to review effectively and complete enough to merge safely. Split unrelated or independently reviewable work into separate pull requests whenever practical.

Keep contribution branches current with master during development by either:

• Rebasing onto master, or
• Merging master into the contribution branch

If you are not comfortable rebasing, merge master into your branch.

The goal is to reduce merge conflicts, expose dependency problems early, and avoid long-lived branch drift.

Before a branch is merged:

• The work has been reviewed.
• Related discussion has been resolved.
• Required checks pass, if checks are configured.
• The branch is sufficiently current with master.
• The pull-request description clearly explains what changed and why.
• Applicable requirements and acceptance criteria are satisfied.
• Affected dependent artifacts are updated or separately tracked.
• Validation and qualification status are stated accurately.
• Unresolved risks and limitations are documented.

Repository maintainers may merge development hardware before physical qualification when its status and limitations are clearly disclosed. Merging establishes the development baseline; it does not by itself qualify hardware for release.

After a pull request is merged, delete the source branch unless it is intentionally retained for continuing coordinated work.

Releases are cut from master because it is the authoritative integration branch.

Project administrators may create temporary release branches or tags for packaging, validation, or rollback. These are administrative release tools rather than normal contributor workflow branches.

Milestones identify the most appropriate target release but are intentionally flexible. Work may move between milestones as priorities, dependencies, qualification, and release scope change.

A trunk-based workflow helps OpenHornet:

• Integrate work more frequently
• Reduce divergence between contributors
• Catch dependency and fitment conflicts earlier
• Simplify the contribution model
• Avoid large, stale, difficult-to-review branches

The normal workflow is:

1. Branch from master.
2. Make a focused change.
3. Commit and push regularly.
4. Open a pull request targeting master.
5. Address review feedback on the same branch.
6. Merge and delete the branch.

Make commits in small, focused increments and push them regularly while work is in progress.

Contributors should push commits on any day when work occurs and preferably as work progresses rather than waiting until the end of the day.

Frequent pushes:

• Reduce duplicated work
• Surface conflicts earlier
• Make review easier
• Provide useful rollback points
• Reduce the risk of lost work

Avoid large, long-running collections of unpushed local commits whenever practical.

Commit subjects should:

• Begin with a capital letter
• Use the imperative mood
• Normally be no more than 50 characters
• Never exceed 72 characters without a specific reason
• Not end with punctuation

A properly formed subject should complete this sentence:

If applied, this commit will [commit subject].

Examples:

• Refactor subsystem X for readability
• Update contributing documentation
• Remove deprecated hardware references
• Release version 1.0.0

The commit body should:

• Use normal capitalization and punctuation
• Explain what changed
• Explain why it changed
• Describe important limitations or consequences
• Reference related issues and pull requests

Example:

Closes: #123
See also: #456, #789

• OpenHornet Contributor Application
• OpenHornet Issue Forms
• OpenHornet Hardware Project Board
• Build Package Requirements
• Generating Fusion 360 Manufacturing Files
• OpenHornet ECAD Requirements
• Generating the JLCPCB Release Package