(GENERATE & INSERT TOC WHEN DONE)

A contribution is where a contributor or a small team of contributors picks an issue from GitHub, ensures requirements are defined fully (working with Noctum or domain lead), works through the steps listed in the appropriate process below, and results in an approved and merged PR to the master branch. If a contributor wants to deviate from the requirements, please talk to Noctum to ensure it is acceptable within the limits of OpenHornet.

The OpenHornet Hardware Project Board is located here. The first 10 or so issues in each domain's TODO column are prioritized, but new contributors should be able to grab a issue labelled good first issue as a good starting place. The labels tell you what they mean if you hover your mouse over them. Prioritize bug/obsolescence labeled issues over enhancement issues.

You can alternatively look at the Issues page for the raw, unprioritized list of OpenHornet Hardware Issues.

While a disciplined approach to contributions is required for OpenHornet to maintain our high quality of this project, we recognize that individuals are contributing on their own time and of their own free will. Spend as much time or as little time as you want. Every contribution is appreciated. We have had contributions from students and individuals with little to no experience, to design professionals from almost every industry in the world.

• Completed OH Contributor Application on file: https://openhornet.com/contributor-application/
• Granted write access to OH F360 Repo by project maintainers. (Request from Noctum on Discord)

• Completed OH Contributor Application on file: https://openhornet.com/contributor-application/
• Use and update existing KiCAD libraries as required.

• GitHub Desktop

• Fusion 360 (F360)
• Shaper Utilities

• KiCAD v9.0.3
• KiCAD JLCPCB tools (com.github.bouni.kicad-jlcpcb-tools) (Install via KiCAD Plugin Manager)

1. Fork the OH repo
   1. Click on the Fork button in the top right corner of the project's GitHub page.
      • This creates a fork of the repository under your github account you can modify at will.
2. Clone the OH repo
   • The first time, you will need to install the github desktop app, open it and login with your GitHub account info. (If you know how to use CLI GIT, this guide is probably too basic for you.)
   1. Open the GitHub Desktop App. Click File > Clone Repository.
   2. Click on the OpenHornet fork under your account, and pick an empty folder for it to clone into. (Caution: its a several gigs of data.)
   3. Click Clone.
      • Now you have a copy of the OpenHornet Project Dev Files on your PC.
3. Select the base branch
   1. Click on Current branch at the top, select the master branch.
4. Create a branch
   1. Click on Current branch at the top, click New Branch, and create a branch.
      • Make sure it's descriptive and follows the guidelines below.
5. Make the change
   • Navigate to the folder you cloned OH to, then make the change(s) you want to contribute back to OpenHornet.
6. Commit the change
   1. After completing your desired change, go back to GitHub desktop app and complete the commit title and descriptions fields.
      • Title should be brief, description should be verbose. Commit frequently, so you have lots of points to roll back to if something doesn't work out.
7. Push the change
   1. Click the button that displays Publish branch to sync changes to GitHub.
      • Now you have the same copy of this branch on your computer as well as on GitHub.
8. Submit a Pull Request
   • This is where you really document the nitty gritty of what you did and why you did it. A Pull Request notifies the project maintainers that you have some work that they should review and eventually add to the project.
   1. Go to the main page of your fork on GitHub and click on the highlighted PR message with a green button displaying Compare & pull request.
   2. Write a title and in the comments section summarize the work you did.
      • Use our template that shows when you create a PR.
      • Be verbose.
      • Be detailed.
      • Add pictures describing your change.
      • Tell us why it changed.
      • Reference an issue.
      • Use the checklist in the PR.
   3. Click Create pull request and leave the box checked that says Allow edits from maintainers.

• That's easy! Just make another commit against the same branch the PR is against and it will apply it to the PR. (Try not to open a new PR unless explicitly instructed to by repository maintainers.)

In a trunk-based workflow, the repository has one primary long-lived branch that represents the current integration point for the project. All contributors branch from it, keep their work small and focused, and merge back into it through pull requests as quickly as practical.

For OpenHornet, the trunk should be the master branch unless the project administrators later choose to rename it to main.

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

The master branch is the single long-lived branch for the repository.

It serves as the shared integration branch for all ongoing work and should always remain in a healthy, reviewable state. All contribution branches are created from master and shall open pull requests back into master.

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

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

Branches should be:

• focused on a single change or tightly related set of changes
• kept as small as practical
• merged back promptly once reviewed
• deleted after merge

Unlike the previous model, there is no permanent develop branch.

• Feature branches are used for new capabilities, new parts, new assemblies, new documentation sections tied to new work, or other additive changes. Example names include: feat/ejection-seat-9-0 or feat/ufcd-backlight-rework.
• Fix branches are used to correct identified problems in hardware, documentation, software, manufacturing files, or supporting materials. Example names include: fix/obsolete-potentiometer or fix/mip-panel-hole-alignment
• Documentation branches are used when the work is documentation-only and is not naturally bundled with another change. Example names include: docs/system-interconnect or docs/contributing-guide-update.
• Chore branches are used for cleanup, refactoring, file organization, naming consistency, standards alignment, or maintenance work that is not a feature and not a bugfix. Example names include: chore/hardware-optimization or chore/normalize-file-names.

Branch names should be descriptive and concise. Use lowercase letters, numbers, and hyphens. The preferred format is: type/short-description. Some examples are: feat/right-console-panel-update, fix/standby-altimeter-clearance, docs/jlcpcb-package-guide, or chore/f360-file-cleanup.

Avoid vague names such as johns-branch, stuff, new-update, or test.

All pull requests shall target master.

A pull request should represent a change that is small enough to review effectively and complete enough to merge safely. If a change grows too large, split it into multiple pull requests whenever practical.

Because trunk-based development relies on frequent integration, contributors should keep their branch current with master throughout development.

This can be done by regularly:

• rebasing onto master, or
• merging master into the branch

If you are not comfortable with rebasing, use a normal merge from master into your branch.

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

Before a branch is merged:

• the work should be reviewed
• related discussion should be resolved
• required checks should pass, if checks are configured
• the contributor should ensure the branch is up to date with master
• the PR description should clearly explain what changed and why

Once merged, the source branch should be deleted.

In this model, releases are cut from master, because master is the trunk and the authoritative integration branch.

Project administrators may create temporary release tags or release branches if needed for packaging, validation, or rollback purposes, but those are administrative release tools - not normal contributor workflow branches.

A trunk-based workflow helps OpenHornet:

• integrate work more often
• reduce divergence between contributors
• catch dependency and fitment conflicts earlier
• simplify the contribution model for new contributors
• avoid large, stale, hard-to-review branches

The expectation is simple:

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

Commits should be made in small, focused increments and pushed to the remote repository regularly while work is in progress.

Contributors should push commits on any day work has taken place, and preferably push as work progresses rather than waiting until the end of the day.

Frequent pushes help:

• reduce duplicated effort
• surface conflicts earlier
• make review easier
• reduce the risk of lost work

Large, long-running sets of unpushed local commits should be avoided whenever practical.

• The commit subject should be capitalized.
• The commit subject should be no more than 50 characters in length, with limited flexibility up to 72 characters as a hard maximum.
• The commit subject should not contain punctuation at the end.
• The commit subject should use the imperative mood (for example, "Refactor subsystem X" or "Update getting started documentation").
• A properly formed Git commit subject line should always be able to complete the following sentence:
  • If applied, this commit will your subject line here
  • For example:
    • If applied, this commit will Refactor subsystem X for readability
    • If applied, this commit will Update getting started documentation
    • If applied, this commit will Remove deprecated methods
    • If applied, this commit will Release version 1.0.0
    • If applied, this commit will Merge pull request #123 from user/branch
• The commit message body should use proper capitalization and punctuation.
• The commit message body should be detailed enough that the reader can understand the changes made and why they were made.
• The commit message body should reference related issues and pull requests at the end when applicable. Example:

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

• Build Package Requirements
• Generating F360 Manufacturing Files
• Generating JLCPCB Release Package