From 89e09cc41bd784f0382d965b108b5dc2e4dc34da Mon Sep 17 00:00:00 2001 From: Yash Nitin Virulkar Date: Tue, 26 May 2026 14:38:44 +0530 Subject: [PATCH] docs(Contributions):added the parameters and guides for contributions to be followed in this org --- CONTRIBUTING.md | 353 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 353 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..97f4ee3 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,353 @@ +# Contributing to Crown-OS + +Crown-OS is an AI-ready, Arch-based Linux distribution. This guide applies to all repositories in the [Crown-OS](https://github.com/Crown-OS) organization. + +## Maintainers + +| GitHub | Role | +|---|---| +| [@Viscous106](https://github.com/Viscous106) | Core maintainer | +| [@marvelxcodes](https://github.com/marvelxcodes) | Core maintainer | +| [@joe-Daniel29](https://github.com/joe-Daniel29) | Core maintainer | + +All PRs require approval from one of the above before merge. + +--- + +## Quickstart + +```bash +# 1. Fork the target repo on GitHub, then clone your fork +git clone git@github.com:/.git && cd + +# 2. Create a branch +git checkout -b feat/your-feature + +# 3. Make focused commits (see Commit Messages below) +git commit -s -m "feat(compositor): add corner radius animation" + +# 4. Rebase onto current main before opening a PR +git fetch origin && git rebase origin/main + +# 5. Open a PR — mark as Draft if work is still in progress +``` + +That's the core loop. The sections below explain each step in detail. + +--- + +## Project Layout + +Crown-OS is a **multi-repo** organization. Each repo has its own dev-setup instructions in its own `CONTRIBUTING.md` stub. The canonical guide is this document. + +| Repository | Purpose | Primary language | +|---|---|---| +| `Crownpositor` | Wayland compositor + shell crates | Rust | +| `crowncrate-linux` | Ecosystem daemon (port 5252) | Rust | +| `CrownCrate` | Desktop app (Tauri + Solid.js) | TypeScript / Rust | +| `crowncrate-android` | Android companion | Kotlin | +| `crownos-iso` | Bootable archiso installer | Bash / config | +| `crownos-website` | Marketing site (Next.js) | TypeScript | +| `crownos-documentations` | This repo — all documentation | Markdown | + +For architecture context, read [`CLAUDE.md`](../CLAUDE.md) at the workspace root. + +--- + +## Branch Naming + +Use the same type prefix as your commit message: + +| Branch prefix | Use for | +|---|---| +| `feat/` | New features | +| `fix/` | Bug fixes | +| `docs/` | Documentation changes | +| `refactor/` | Refactoring without behavior change | +| `chore/` | Maintenance — deps, tooling, config | +| `ci/` | CI/CD pipeline changes | +| `test/` | Adding or fixing tests | + +**Format:** `/` + +``` +feat/clipboard-sync-daemon +fix/compositor-crash-on-resize +docs/contribution-guide +chore/bump-smithay-0.8 +``` + +--- + +## Commit Messages + +Crown-OS enforces [Conventional Commits 1.0](https://www.conventionalcommits.org/en/v1.0.0/). CI rejects non-compliant commits. + +### Format + +``` +(): + +[optional body] + +[optional footers] +``` + +### Rules + +- **Subject line:** lowercase, imperative mood, no trailing period, max 72 characters +- **Body:** wrap at 72 characters, explain *why* not *what* +- **Breaking changes:** add `BREAKING CHANGE: ` in the footer +- **DCO sign-off required:** every commit must be signed with `git commit -s` + +### Types + +| Type | Use for | +|---|---| +| `feat` | New user-facing feature | +| `fix` | Bug fix | +| `docs` | Documentation only | +| `refactor` | Code change — no feature, no fix | +| `test` | Adding or correcting tests | +| `perf` | Performance improvement | +| `chore` | Tooling, deps, build, config | +| `ci` | CI/CD pipeline changes | +| `style` | Formatting only — no logic change | +| `revert` | Reverts a prior commit | + +### Scopes + +Use the scope that matches the affected repository or crate: + +| Scope | Covers | +|---|---| +| `compositor` | `Crownpositor/crates/compositor` | +| `bar` | `Crownpositor/crates/bar` | +| `launcher` | `Crownpositor/crates/launcher` | +| `notification` | `Crownpositor/crates/notification` | +| `greeter` | `Crownpositor/crates/greeter` | +| `dropshare` | `Crownpositor/crates/dropshare` | +| `crownpositor` | Workspace-level `Crownpositor` changes | +| `crowncrate` | `CrownCrate` desktop app | +| `crowncrate-linux` | `crowncrate-linux` daemon | +| `android` | `crowncrate-android` | +| `iso` | `crownos-iso` | +| `website` | `crownos-website` | +| `docs` | `crownos-documentations` | +| `ci` | Any repo's CI pipeline | + +### Examples + +``` +feat(compositor): implement layer-shell surface support + +fix(crowncrate-linux): resolve clipboard sync race on rapid paste + +chore(crowncrate): bump smithay to 0.8 + +docs(contribution): add branch naming convention section + +feat(android)!: migrate protocol to CBOR v2 + +BREAKING CHANGE: devices running the old JSON protocol must upgrade +crowncrate-linux before pairing. +``` + +--- + +## Keeping Your Branch Clean + +Crown-OS uses **rebase merge**. Every commit from your PR lands individually on `main`. This means: + +1. Each commit must pass CI on its own. +2. `main` stays perfectly linear — easy to `git bisect`. +3. WIP / fixup commits must be cleaned before review. + +### Before requesting review + +**Squash fixups into their parent commit:** + +```bash +# Mark fixup commits at staging time +git commit --fixup HEAD + +# Then collapse them +git rebase -i --autosquash origin/main +``` + +**Rebase onto current main:** + +```bash +git fetch origin +git rebase origin/main +``` + +**Force-push to your branch** (your branch, never `main`): + +```bash +git push --force-with-lease origin feat/your-feature +``` + +### Commit hygiene checklist + +Before marking a PR ready for review, each commit should: + +- [ ] Compile and pass tests independently (`cargo check`, `bun run check-types`, etc.) +- [ ] Have a valid Conventional Commits message +- [ ] Be signed off (`Signed-off-by:` line present — added by `git commit -s`) +- [ ] Not bundle unrelated changes + +--- + +## Pull Request Process + +### Opening a PR + +1. Push your branch and open a PR against `main`. +2. Use **Draft PR** if the work is still in progress — it's encouraged for early feedback. +3. Fill in the PR template (auto-populated on GitHub) — the **Closes** field is required. + +### PR template + +```markdown +## Closes + + + + + +Closes # + +## Summary + + +## Changes + + +## Testing + + +## Checklist +- [ ] Linked issue in the "Closes" section above +- [ ] Each commit follows Conventional Commits +- [ ] Each commit is signed off (`git commit -s`) +- [ ] Each commit compiles and passes CI independently +- [ ] Branch is rebased onto current `main` +- [ ] Relevant tests added or updated +``` + +### Review requirements + +- **CI must pass** — all checks green before review is requested. +- **Linked issue required** — every PR must close an issue; PRs without a `Closes #` line will be returned to the author. +- **One maintainer approval required** — [@Viscous106](https://github.com/Viscous106), [@marvelxcodes](https://github.com/marvelxcodes), or [@joe-Daniel29](https://github.com/joe-Daniel29). Enforced via CODEOWNERS. +- **No unresolved review threads** — address or explicitly dismiss all comments before merge. +- Maintainers may request a rebase if `main` has moved significantly. + +### Merge + +Maintainers merge using **rebase merge only**. Do not use squash or merge commits — the repo is configured to disable them. + +--- + +## Code Standards + +Automated formatters and linters run in CI. Run them locally before pushing. + +### Rust (Crownpositor, crowncrate-linux, CrownCrate src-tauri) + +```bash +cargo fmt --all # format +cargo clippy --all-targets --all-features -- -D warnings # lint +cargo test --all # tests +``` + +- Follow `rustfmt` defaults — no manual overrides. +- All `clippy` warnings are errors in CI. +- Use `edition = "2024"` in all new crates. +- Minimize comments: only write one when the *why* is non-obvious. + +### TypeScript / Solid.js (CrownCrate, crownos-website) + +```bash +bun run lint # biome lint +bun run format # biome format +bun run check-types # tsc --noEmit +``` + +- [Biome](https://biomejs.dev/) handles both linting and formatting. No ESLint, no Prettier. +- `crownos-website`: run `bun run lint` (Biome) in the website repo. + +### Kotlin (crowncrate-android) + +```bash +./gradlew ktlintCheck # lint +./gradlew ktlintFormat # format +./gradlew test # unit tests +``` + +- Follows the official [Kotlin coding conventions](https://kotlinlang.org/docs/coding-conventions.html). +- Jetpack Compose: prefer stateless composables, hoist state. + +### Shell / archiso (crownos-iso) + +```bash +shellcheck airootfs/**/*.sh +``` + +- All shell scripts must pass `shellcheck` with no warnings. + +--- + +## Issue Reporting + +Use GitHub Issues on the relevant repository. + +### Bug report + +Include: +- Crown-OS version or commit hash +- Steps to reproduce (minimal) +- Expected vs. actual behavior +- System info: GPU, display server, relevant package versions + +### Feature request + +Include: +- The problem you're solving (not just the solution) +- How it fits the Crown-OS design language (monochromatic, minimal, professional) +- Whether it touches a single repo or multiple + +### Security vulnerabilities + +**Do not open a public issue.** Report via [GitHub private security advisories](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing/privately-reporting-a-security-vulnerability) on the affected repository. + +--- + +## DCO Sign-off + +Crown-OS uses the [Developer Certificate of Origin (DCO)](https://developercertificate.org/). Every commit must contain: + +``` +Signed-off-by: Your Name +``` + +Add it automatically with `git commit -s`. By signing off you certify that you have the right to submit the contribution under the project's license. + +--- + +## Releases and Changelog + +Changelogs are auto-generated from Conventional Commits. Breaking changes (`BREAKING CHANGE:` footer or `!` type suffix) trigger a major version bump. Release cadence is TBD — changelogs will be published in this documentation repo when releases begin. + +--- + +## Code of Conduct + +Crown-OS follows the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). By contributing you agree to abide by its terms. + +--- + +## Questions + +Open a Discussion on the relevant GitHub repository or file an issue tagged `question`.