Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
docs: document the contribution and review workflow
Brendan O'Leary committed
Sep 10, 2026 at 11:19 UTC
d9e4b78653b58fc1ccd19b0a7a0c60a7f51996c5
2 files changed
+64
-1
docs/CONTRIBUTING.md
new
+61
@@ -0,0 +1,61 @@
1
+# Change the Composio docs
2
+
3
+Use a pull request for a specific docs fix. Use a Developer Marketing issue in Linear with the Docs label when the work needs investigation, coordination, or a larger content plan. Link the issue and its source context in the PR so the reviewer can check the original problem.
4
+
5
+For a runtime bug, include a reproducible example and involve the SDK or platform owner. A docs change cannot establish behavior that the product does not support.
6
+
7
+## Choose the source
8
+
9
+| Change | Edit |
10
+| --- | --- |
11
+| A guide or explanation | `content/docs/` |
12
+| An application example | `content/examples/` |
13
+| A release note | `content/changelog/` and the [changelog guide](agent-guidance/guides/changelog.md) |
14
+| Sidebar order | The nearest `meta.json`; product navigation also uses `lib/home-navigation.ts` |
15
+| Page layout or an MDX component | `app/`, `components/`, or `lib/` |
16
+| API or SDK reference, toolkit data | The owning source or generator; do not patch generated output by hand |
17
+| A public support answer | The [knowledge publication workflow](decisions/public-knowledge-base.md) |
18
+
19
+Read [AGENTS.md](AGENTS.md) for repository rules. For typed code examples, read the [Twoslash guide](agent-guidance/context/twoslash.md). Check the [docs decisions](decisions/README.md) before changing an established architecture or content pipeline.
20
+
21
+## Prepare a change
22
+
23
+1. Find the existing page and search for related issues or PRs. Extend the canonical page when it already covers the topic.
24
+2. Branch from the latest `origin/next`. Target the PR at `next`.
25
+3. Reproduce the problem or write down the reader's task and the expected result. Include the affected URL and source evidence.
26
+4. Verify API behavior against SDK code, the current API schema, or a reproducible request. For an unresolved product or architecture question, get confirmation from the responsible team before documenting a recommendation.
27
+5. Make the smallest complete change. Use relative site links, add new pages to navigation, and preserve the Markdown representation of task-critical content.
28
+
29
+From the repository root, install the pinned toolchain with `mise install`. Then run the docs commands from `docs/`:
30
+
31
+```bash
32
+bun install
33
+bun run dev
34
+```
35
+
36
+Open the changed page at `http://localhost:3000`. Inspect its layout, links, and code examples. Also inspect its `.md` URL if the change contains commands, warnings, component content, or navigation.
37
+
38
+## Validate the PR
39
+
40
+Run these checks from `docs/`:
41
+
42
+```bash
43
+bun run test
44
+bun run lint
45
+bun run lint:links
46
+bun run types:check
47
+bun run check:kb-semantic
48
+bun run build
49
+```
50
+
51
+To check the built site's endpoints, run `bun run start` in one terminal and `bun run test:integration` in another. The integration tests use `http://localhost:3000` by default. Set `TEST_BASE_URL` if your server uses another address.
52
+
53
+A stale KB semantic artifact can follow a content change. The `Docs - Rebuild KB Semantic Artifact` workflow can rebuild it for eligible same-repository PRs after `Docs - Tests` runs. Check that workflow's result and rerun failed checks against the updated commit. If you rebuild locally with `bun run build:kb-semantic`, use an authorized `OPENAI_API_KEY`: the generator sends the indexed docs content to the embeddings service. Never edit embedding values or content hashes by hand.
54
+
55
+## Request review and verify publication
56
+
57
+Describe the reader's problem, the resulting behavior, and the checks you ran. Include screenshots for visual changes and list checks that failed or could not run. Link the Linear issue when one exists. Docs-only changes do not need a Changeset.
58
+
59
+Request review from someone who can verify the changed topic. Involve the product owner for behavior, security, tenancy, or contractual claims. Follow the repository's review and merge requirements; a passing build alone does not verify those claims.
60
+
61
+After merge, confirm the deployment succeeds and inspect the live page and `.md` representation. Check `Docs - Sync Algolia Search` for changes that affect retrieval. Update the linked issue with the published result once the change is verified. If the live result is wrong, report the affected URL and commit so the next fix starts from evidence.
docs/README.md
+3
-1
@@ -2,6 +2,8 @@
2
3
Documentation site for Composio, built with [Fumadocs](https://fumadocs.dev/).
4
5
+For issue triage, review, validation, and publication, follow [Change the Composio docs](CONTRIBUTING.md).
6
+
7
## Getting Started
8
9
```bash
@@ -72,7 +74,7 @@ All TypeScript code blocks in MDX files are **type-checked at build time** using
74
- Use `// ---cut---` to hide setup code from output
75
- Run `bun run build` locally to validate before pushing
76
75
-See `CLAUDE.md` for detailed patterns and troubleshooting.
77
+See the [Twoslash guide](agent-guidance/context/twoslash.md) for complete example patterns and troubleshooting.
78
79
## Search
80