Merge pull request #147 from stephenleo/docs/contribution-guide

docs: add contribution guide and BMAD workflow

Author: stephenleo

.github/workflows/claude-code-review.yml

@@ -1,23 +1,15 @@
 name: Claude Code Review
 
 on:
-  pull_request:
-    types: [opened, synchronize, ready_for_review, reopened]
-    # Optional: Only run on specific file changes
-    # paths:
-    #   - "src/**/*.ts"
-    #   - "src/**/*.tsx"
-    #   - "src/**/*.js"
-    #   - "src/**/*.jsx"
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: 'Pull request number to review'
+        required: true
+        type: number
 
 jobs:
   claude-review:
-    # Optional: Filter by PR author
-    # if: |
-    #   github.event.pull_request.user.login == 'external-contributor' ||
-    #   github.event.pull_request.user.login == 'new-developer' ||
-    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
-
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -38,7 +30,6 @@ jobs:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
           plugins: 'code-review@claude-code-plugins'
-          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }} --comment'
+          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ inputs.pr_number }} --comment'
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
           # or https://code.claude.com/docs/en/cli-reference for available options
-

CLAUDE.md

@@ -12,6 +12,7 @@
 - stdout owned by `main.rs` only; all module diagnostics via `tracing::*` macros; no `eprintln!` anywhere
 - Exception: CLI-action subcommands (e.g. `uninstall`, `explain`) may use `println!` directly — the stdout rule applies to the rendering pipeline only
 - All config structs: `#[derive(Debug, Deserialize, Default)]`, all fields `pub Option<T>`
+- Never add `deny_unknown_fields` to any struct — omitted intentionally on both `Context` and config structs so future Claude Code versions can add fields without breaking deserialization
 
 ## Project Structure
 - Adding a native module: create `src/modules/{name}.rs` + update `src/modules/mod.rs` only (2 files max)

CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing to CShip
+
+Thank you for contributing! This guide explains how to get your changes ready to pass CI.
+
+## Prerequisites
+
+- [Rust toolchain](https://rustup.rs) (stable)
+
+## Running checks before submitting a PR
+
+CI enforces four checks. Run them locally before pushing:
+
+```sh
+# 1. Format — CI runs `cargo fmt --check`; fix formatting first
+cargo fmt
+
+# 2. Lint — all Clippy warnings are treated as errors
+cargo clippy -- -D warnings
+
+# 3. Tests
+cargo test
+
+# 4. Release build
+cargo build --release
+```
+
+If any of these fail locally, they will fail in CI. Fix them before opening a PR.
+
+## Adding a new module
+
+### BMAD (Recommended)
+
+This project is built with [BMAD](https://github.com/bmad-code-org/BMAD-METHOD).
+
+1. Install BMAD in this repo. `npx bmad-method install`
+2. Run `/bmad-quick-dev` with a GitHub issue URL or a description of your change — it guides you from intent through spec, implementation, and review.
+
+### Manual (Not recommended)
+
+See the non-negotiable code patterns in `CLAUDE.md`.
+
+- Create `src/modules/{name}.rs` and update `src/modules/mod.rs`. If the module needs config fields, also add a struct to `src/config.rs`.
+- Module signature: `pub fn render(ctx: &Context, cfg: &CshipConfig) -> Option<String>`
+- All config structs go in `src/config.rs` with `#[derive(Debug, Deserialize, Default)]` and `pub Option<T>` fields.
+- Absent data → explicit `match` + `tracing::warn!` + `None`. Disabled flag → silent `None`. (Exception: `context_bar` renders an empty bar with `tracing::debug!` when context data is absent — this is intentional UX.)
+
+## Updating documentation
+
+Most documentation lives in `docs/`; `CONTRIBUTING.md` at the repo root mirrors `docs/contributing.md` (see the last bullet). Update the relevant files alongside your code change:
+
+- **New module or config field** — add the config option to `docs/configuration.md`. If the module has non-obvious UX, add a `docs/faq.md` entry too.
+- **Removed module or config field** — delete or mark deprecated the corresponding entry in `docs/configuration.md`.
+- **Behaviour change** — update any affected section in `docs/configuration.md` or `docs/faq.md`.
+- **New showcase or example** — add the `cship.toml` config block to `docs/showcase.md` and place any screenshot or GIF in `docs/examples/`.
+- **This guide** — `CONTRIBUTING.md` (repo root) and `docs/contributing.md` are kept in sync manually; if you edit either for any reason, update the other to match.
+
+## Opening a PR
+
+1. Make sure all four checks above pass.
+2. Describe what your change does and why in the PR description.
+3. Reference any related issues with `Closes #<issue-number>`.

README.md

@@ -248,7 +248,7 @@ critical_style     = "bold red"
 
 Every style value is a `fg:#rrggbb` hex colour — no named colours anywhere. Amber warns, coral criticals.
 
-`<img src="./docs/examples/06.png" alt="Material Hex cship statusline example" width="600">
+<img src="./docs/examples/06.png" alt="Material Hex cship statusline example" width="600">
 
 <details>
 <summary>View config</summary>
@@ -477,6 +477,14 @@ If you found this project useful, please give us a star ⭐ on [GitHub](https://
 
 If you find bugs or have suggestions, open an issue or submit a pull request. Contributions are very welcome!
 
+Before submitting a PR, run the following to match what CI checks:
+
+```sh
+cargo fmt && cargo clippy -- -D warnings && cargo test && cargo build --release
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full details.
+
 ## 💡 Inspiration
 - Inspired by [starship](https://starship.rs), built with Rust and the [Claude Code status line API](https://code.claude.com/docs/en/statusline).
 

docs/.vitepress/config.mts

@@ -21,6 +21,7 @@ export default defineConfig({
       { text: 'Passthrough', link: '/passthrough' },
       { text: 'Showcase', link: '/showcase' },
       { text: 'FAQ', link: '/faq' },
+      { text: 'Contributing', link: '/contributing' },
       {
         text: 'GitHub',
         link: 'https://github.com/stephenleo/cship',
@@ -46,6 +47,7 @@ export default defineConfig({
         items: [
           { text: 'Showcase', link: '/showcase' },
           { text: 'FAQ', link: '/faq' },
+          { text: 'Contributing', link: '/contributing' },
         ],
       },
     ],

docs/contributing.md

@@ -0,0 +1,59 @@
+# Contributing
+
+Thank you for contributing to CShip!
+
+## Prerequisites
+
+- [Rust toolchain](https://rustup.rs) (stable)
+
+## Checks to run before submitting a PR
+
+CI enforces four checks on every pull request. Run them locally before pushing to avoid failing builds:
+
+```sh
+# 1. Format — CI runs `cargo fmt --check`; fix formatting first
+cargo fmt
+
+# 2. Lint — all Clippy warnings are treated as errors
+cargo clippy -- -D warnings
+
+# 3. Tests
+cargo test
+
+# 4. Release build
+cargo build --release
+```
+
+If any of these fail locally, they will fail in CI. Fix them before opening a PR.
+
+## Adding a new module
+
+### BMAD (Recommended)
+
+This project is built with [BMAD](https://github.com/bmad-code-org/BMAD-METHOD).
+
+1. Install BMAD in this repo. `npx bmad-method install`
+2. Run `/bmad-quick-dev` with a GitHub issue URL or a description of your change — it guides you from intent through spec, implementation, and review.
+
+### Manual (Not recommended)
+
+- Create `src/modules/{name}.rs` and update `src/modules/mod.rs`. If the module needs config fields, also add a struct to `src/config.rs`.
+- Module signature must be exactly: `pub fn render(ctx: &Context, cfg: &CshipConfig) -> Option<String>`
+- All config structs go in `src/config.rs` with `#[derive(Debug, Deserialize, Default)]` and `pub Option<T>` fields.
+- Absent data → explicit `match` + `tracing::warn!` + `None`. Disabled flag → silent `None`. (Exception: `context_bar` renders an empty bar with `tracing::debug!` when context data is absent — this is intentional UX.)
+
+## Updating documentation
+
+Most documentation lives in `docs/`; `CONTRIBUTING.md` at the repo root mirrors `docs/contributing.md` (see the last bullet). Update the relevant files alongside your code change:
+
+- **New module or config field** — add the config option to `docs/configuration.md`. If the module has non-obvious UX, add a `docs/faq.md` entry too.
+- **Removed module or config field** — delete or mark deprecated the corresponding entry in `docs/configuration.md`.
+- **Behaviour change** — update any affected section in `docs/configuration.md` or `docs/faq.md`.
+- **New showcase or example** — add the `cship.toml` config block to `docs/showcase.md` and place any screenshot or GIF in `docs/examples/`.
+- **This guide** — `CONTRIBUTING.md` (repo root) and `docs/contributing.md` are kept in sync manually; if you edit either for any reason, update the other to match.
+
+## Opening a PR
+
+1. Make sure all four checks above pass.
+2. Describe what your change does and why in the PR description.
+3. Reference any related issues with `Closes #<issue-number>`.