g1t/CONTRIBUTING.md
| 1 | # Contributing to g1t |
| 2 | |
| 3 | g1t is built the way it asks others to build: issues and pull requests on |
| 4 | [g1t.sh/flagon-io/g1t](https://g1t.sh/flagon-io/g1t), required checks that prove |
| 5 | a change works, and a merge queue that keeps `main` passing. |
| 6 | |
| 7 | ## A change ships with its docs |
| 8 | |
| 9 | Documentation is part of the product, held to the same bar as the code. |
| 10 | A pull request that changes what someone can do, see or call changes the |
| 11 | docs in the same pull request: |
| 12 | |
| 13 | | If you change | Update | |
| 14 | | --- | --- | |
| 15 | | Something a person does on g1t.sh | The guide for it in `apps/docs/src/content/docs/guides/` | |
| 16 | | An API route, a field, or an MCP tool | `apps/api/src/operations.rs` descriptions (they feed the OpenAPI document and the API reference), the example and notes for it in `apps/api/src/reference.json`, `reference/mcp.md`, and any guide that shows the call. Then refresh the docs' copy of the OpenAPI document with `G1T_WRITE_OPENAPI=1 cargo test -p g1t-api openapi`; `cargo test` fails until you do. | |
| 17 | | How agents behave | `guides/working-with-g1t.md`, and `apps/web/public/llms.txt` | |
| 18 | | Settings, limits or prices | The page that names them, and the table it is in | |
| 19 | | A new feature | A section in the guide that owns it, linked from the docs home if it is a new task | |
| 20 | |
| 21 | The style, in short: plain sentences, second person, no marketing words, |
| 22 | sentence-case headings, a numbered list for steps, a table for options, and |
| 23 | every API mention with its exact route or tool name. Examples are copyable |
| 24 | and real. Nothing is documented that the code does not do. |
| 25 | |
| 26 | Check the docs build before you push: |
| 27 | |
| 28 | ```sh |
| 29 | cd apps/docs && npm run build |
| 30 | ``` |
| 31 | |
| 32 | ## Icons |
| 33 | |
| 34 | - **Interface icons come from [Lucide](https://lucide.dev/icons).** In the |
| 35 | apps, import them from `lucide-react`. In the docs, use `@lucide/astro`: |
| 36 | import an icon component, or give `apps/docs/src/components/Card.astro` |
| 37 | and `Aside.astro` a Lucide name such as `icon="git-branch"`. Starlight's |
| 38 | own `<Card>`, `<LinkCard>` and `<Aside>` draw Starlight's icon set, so the |
| 39 | docs import the wrappers in `apps/docs/src/components/` instead. |
| 40 | - **Brand marks come from [Simple Icons](https://simpleicons.org)** |
| 41 | (`simple-icons`), and follow each brand's own usage guidelines. Add the |
| 42 | dependency with the first one you show. |
| 43 | - **The g1t logo and illustrations are our own artwork**, in |
| 44 | `apps/web/app/components/logo.tsx` and `art.tsx`. |
| 45 | - Never hand-copy an icon's SVG paths into a file. If Lucide lacks the |
| 46 | icon you need, pick the closest one that it has. |
| 47 | |
| 48 | ## Before you push |
| 49 | |
| 50 | - `cargo test` in the crate or service you changed. |
| 51 | - `npx tsc -b --force` in `apps/web` (the incremental build misses changes |
| 52 | in `packages/contracts`). |
| 53 | - Look at what you changed in a browser. Screenshots catch what type |
| 54 | checks do not. |
| 55 | |
| 56 | ## Deploying |
| 57 | |
| 58 | Pushes to `main` deploy themselves: `.g1t/workflows/deploy.yml` runs |
| 59 | `scripts/deploy.mjs`, which deploys only the parts that changed, migrations |
| 60 | first. Every deployable part is listed in `deploy/stack.jsonc`; a new service |
| 61 | or app goes there (`npm run test:deploy` says what is missing). See |
| 62 | [docs/DEPLOYING.md](docs/DEPLOYING.md) for the tool, the workflow, rollbacks |
| 63 | and adding a service. |