// Moved from docs/src/development/CONTRIBUTING.adoc to docs/working/scratch/src/development/CONTRIBUTING.adoc on 2026-06-16 (docs reorg Phase 2)
== Contributing to StarshipOS
:toc: left
:toc-title: Contents
:toclevels: 3
xref:../README.adoc[← Back to Documentation Index]



Welcome—glad you’re here. This guide tells you how to get set up,
propose changes, and work with maintainers efficiently. It’s opinionated
on purpose so we ship fast and don’t break stuff (or, at least, not
twice).

____
TL;DR

[arabic]
. Fork → branch → small PRs.
. Follow Conventional Commits.
. Run `+make fmt lint test+` before you push.
. Include repro steps, docs, and tests.
. Be kind. Be direct. Don’t ship junk.
____

'''''

=== Code of Conduct

We follow the *Contributor Covenant*. Be respectful, assume good intent,
and focus on the work. Violations can lead to a ban from participation.

* Read: `+CODE_OF_CONDUCT.md+`
* Contact for incidents: coc-contact@example.org

'''''

=== Scope & Architecture (two-minute tour)

* *What this repo is:*
* *What it isn’t:*
* *Key directories:*
** `+cmd/+` – CLI or entrypoints
** `+pkg/+` or `+src/+` – libraries / core
** `+internal/+` – private packages
** `+docs/+` – docs, ADRs, diagrams
** `+test/+` – integration/e2e tests
** `+.github/+` – CI, workflows, templates

Add/update an *ADR* (Architecture Decision Record) for any non-trivial
design choice: `+docs/adrs/ADR-XXXX-title.md+`.

'''''

=== Getting Started

==== Prerequisites

* OS: Linux, macOS, or WSL2
* Tooling: `+git+`, `+make+`, `+docker+` (optional),
`+<language toolchain>+` (e.g., Go, Rust, Node, Python)
* Pre-commit hooks: `+pipx install pre-commit+` (or
`+brew install pre-commit+`) → `+pre-commit install+`

==== Quick Setup

[source,bash]
----
# 1) Fork and clone
 git clone https://github.com/<you>/<PROJECT_NAME>.git
 cd <PROJECT_NAME>

# 2) Bootstrap toolchain (optional if repo provides it)
 make bootstrap   # installs dev deps, pre-commit hooks, etc.

# 3) Verify you can build and test
 make build
 make test
----

==== Local Development Loop

[source,bash]
----
make fmt      # auto-format
make lint     # static analysis
make test     # unit tests
make itest    # integration tests (if available)
make run      # run the app locally
----

If `+make+` isn’t your thing, check `+CONTRIBUTING.md+` for
language-specific commands under *Appendix: Language Notes*.

'''''

=== How to Contribute

We welcome:

* Bug fixes
* Small features
* Docs improvements (user or dev docs)
* Refactors that reduce complexity
* Test coverage and infra tooling

Open an issue first for large or controversial changes so we can align
early.

==== Issues

* *Bug report:* include _exact_ repro steps, logs, and expected
vs. actual behavior. Minimal repros beat novels.
* *Feature request:* explain the problem first; propose an API/UX; add a
success metric.
* *Labels:* maintainers triage with `+kind/*+`, `+area/*+`,
`+priority/*+`, `+good-first-issue+`, etc.

==== Branching

* Base: `+main+` is the trunk; it must be green.
* Branch names: `+feat/<slug>+`, `+fix/<slug>+`, `+docs/<slug>+`,
`+chore/<slug>+`.

==== Commit Style (Conventional Commits)

We use *Conventional Commits* to automate changelogs and releases.
Examples:

....
feat(runtime): add cgroups v2 isolation flag
fix(scheduler): prevent null deref on empty queue
docs: clarify quickstart on macOS
chore(ci): bump golangci-lint to 1.60
refactor(vm): split hypervisor interface
....

* Use the imperative mood.
* Keep the subject ≤ 72 chars; add a body if needed.
* Reference issues like `+Fixes #123+` or `+Refs #456+`.

==== Signed-Off-By (DCO)

This project uses the *Developer Certificate of Origin (DCO)*. Add a
sign-off to every commit:

....
Signed-off-by: Your Name <you@example.com>
....

You can automate it:

[source,bash]
----
git config --global commit.gpgsign true         # if you sign commits
git config --global user.name "Your Name"
git config --global user.email you@example.com
alias gcs="git commit -s"                        # always add DCO sign-off
----

____
If your organization requires a CLA instead, link it here and state the
rules.
____

'''''

=== Pull Requests

* *Keep PRs small* (under ~300 lines changed when possible). Big bang
PRs sit and rot.
* *Checklist:*
** [ ] Issue linked (or rationale explained)
** [ ] Tests added/updated
** [ ] Docs updated (`+README+`, `+docs/+`, examples)
** [ ] `+make fmt lint test+` passes locally
** [ ] Backwards compatibility considered
** [ ] Performance impact measured (if relevant)
* Draft PRs welcome early—mark as “Read