Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 03:37 UTC
| 1 | # Change the Composio docs |
| 2 | |
| 3 | Use a pull request for a specific docs fix. For Composio team members, 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 | Composio team members and designated maintainers can open PRs directly. External contributors need an existing, open GitHub issue. For large external changes, get maintainer agreement on the approach before implementation. Read the root [Contribution Policy](../CONTRIBUTING.md#contribution-policy), including the [third-party links policy](../CONTRIBUTING.md#third-party-links-in-docs). Authoritative technical references needed to use or contribute to Composio are allowed. For a partnership request, contact us through [composio.dev/contact](https://composio.dev/contact). |
| 6 | |
| 7 | 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. |
| 8 | |
| 9 | ## Choose the source |
| 10 | |
| 11 | | Change | Edit | |
| 12 | | --- | --- | |
| 13 | | A guide or explanation | `content/docs/` | |
| 14 | | An application example | `content/examples/` | |
| 15 | | A release note | `content/changelog/` and the [changelog guide](agent-guidance/guides/changelog.md) | |
| 16 | | Sidebar order | The nearest `meta.json`; product navigation also uses `lib/home-navigation.ts` | |
| 17 | | Page layout or an MDX component | `app/`, `components/`, or `lib/` | |
| 18 | | API or SDK reference, toolkit data | The owning source or generator; do not patch generated output by hand | |
| 19 | | A public support answer | The [knowledge publication workflow](decisions/public-knowledge-base.md) | |
| 20 | |
| 21 | 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. |
| 22 | |
| 23 | ## Prepare a change |
| 24 | |
| 25 | 1. Find the existing page and search for related issues or PRs. Extend the canonical page when it already covers the topic. |
| 26 | 2. Branch from the latest `origin/next`. Target the PR at `next`. |
| 27 | 3. Reproduce the problem or write down the reader's task and the expected result. Include the affected URL and source evidence. |
| 28 | 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. |
| 29 | 5. Make the smallest complete change. Use relative site links, add new pages to navigation, and preserve the Markdown representation of task-critical content. |
| 30 | |
| 31 | From the repository root, install the pinned toolchain with `mise install`. Then run the docs commands from `docs/`: |
| 32 | |
| 33 | ```bash |
| 34 | bun install |
| 35 | bun run dev |
| 36 | ``` |
| 37 | |
| 38 | 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. |
| 39 | |
| 40 | ## Validate the PR |
| 41 | |
| 42 | Run these checks from `docs/`: |
| 43 | |
| 44 | ```bash |
| 45 | bun run test |
| 46 | bun run lint |
| 47 | bun run lint:links |
| 48 | bun run types:check |
| 49 | bun run check:kb-semantic --allow-stale |
| 50 | bun run build |
| 51 | ``` |
| 52 | |
| 53 | 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. |
| 54 | |
| 55 | The semantic artifact covers both regular docs and KB articles, so edits to either can make it stale. PR checks use `--allow-stale` to warn about freshness while still rejecting missing or corrupt artifacts. Search falls back to keyword results until the artifact is rebuilt. |
| 56 | |
| 57 | The `Docs - Rebuild KB Semantic Artifact` workflow can rebuild it for eligible same-repository PRs after `Docs - Tests` runs. The scheduled `Docs - Repair KB Semantic Artifact` workflow also proposes repairs for anything that reached `next` stale. 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. Run `bun run check:kb-semantic` without `--allow-stale` to verify a rebuild. Never edit embedding values or content hashes by hand. |
| 58 | |
| 59 | ## Agent-readable representations |
| 60 | |
| 61 | Request a page with `Accept: text/markdown` (or `text/plain`), append `.md` or `.mdx`, or use its `/llms.mdx/` route. HTML pages with a Markdown representation advertise it with `<link rel="alternate" type="text/markdown">`. Negotiated responses include `Vary: Accept` so caches distinguish HTML from Markdown. |
| 62 | |
| 63 | Next.js `16.3.8` replaces middleware's `Vary` header in its Node HTML response template. The docs package carries a two-line dependency patch that appends Next's cache dimensions instead. The upstream regression is tracked in [Next.js issue #85852](https://github.com/vercel/next.js/issues/85852). Keep the live negotiation test when upgrading Next. Remove the patch once an unpatched production build passes that test. |
| 64 | |
| 65 | Per-page Markdown starts with YAML front matter. For example, `/reference/authenticating-to-composio.md` identifies its HTML and Markdown URLs independently of the URL you requested: |
| 66 | |
| 67 | ```yaml |
| 68 | --- |
| 69 | canonical_url: "https://docs.composio.dev/reference/authenticating-to-composio" |
| 70 | markdown_url: "https://docs.composio.dev/reference/authenticating-to-composio.md" |
| 71 | product: "platform" |
| 72 | version: "3.1" |
| 73 | last_updated: null |
| 74 | --- |
| 75 | ``` |
| 76 | |
| 77 | `product` uses the URL-based docs product, `platform` or `for-you`, without reading your product cookie. Shared pages default to `platform`. `version` is the documented REST version (`3.1` or legacy `3.0`), or `null` for pages that don't document a REST version. It isn't an SDK package version. `last_updated` is a UTC ISO 8601 timestamp, or `null` when freshness can't be established. The example uses `null`, not an invented update time. |
| 78 | |
| 79 | The sitemap's `lastmod` and Markdown's `last_updated` use the same build-generated source freshness data. They never use build time or filesystem modification time. Missing pages return Markdown discovery and search links with HTTP `404`; error responses don't claim a content update time. |
| 80 | |
| 81 | The prebuild, predev, and type-check steps generate `.generated/content-freshness.json` from each page's backing files. Deployed routes read that artifact without Git. Freshness is limited to authored pages and dated changelog entries. Generated API and toolkit pages, KB guides, and browse pages return `last_updated: null` and omit sitemap `lastmod`. Their shared specifications, catalogs, or manifests can change without changing the page. Add timestamps for these pages only when changes can be attributed to each page. |
| 82 | |
| 83 | You can declare `last_updated: YYYY-MM-DD` or a timezone-qualified ISO timestamp in authored front matter. A date-only value means midnight UTC; an invalid value fails generation. Otherwise, freshness uses the source file's last Git commit. Dated changelog pages use the latest known update across entries for that date. A source commit records an edit, not a review or a guarantee that the guidance is current. |
| 84 | |
| 85 | Docs CI fetches full history. The Vercel build command fetches missing history before running `bun run build`. If that fetch fails, the deployment fails instead of silently publishing incomplete freshness. For other CI/CD builds, provide full history (`fetch-depth: 0` with `actions/checkout`) for complete freshness coverage. A shallow checkout retains dates for changes proven within its history but omits unknown shallow-boundary dates. Source archives without history also omit unknown dates. Neither case substitutes the checkout or build time. |
| 86 | |
| 87 | ## Request review and verify publication |
| 88 | |
| 89 | 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. |
| 90 | |
| 91 | Request review from [@jkomyno](mailto:alberto@composio.dev), the designated PR reviewer, and involve 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. |
| 92 | |
| 93 | 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. |