From 6e889c4f9455b761a858a239da6b938e3cd1d326 Mon Sep 17 00:00:00 2001 From: synchwire Date: Sun, 26 Apr 2026 00:41:35 +0100 Subject: [PATCH 1/2] chore: add CI, dependabot, and CONTRIBUTING - CI builds the site on every PR and on push to main - Dependabot bumps npm and GitHub Actions weekly; Astro packages grouped - CONTRIBUTING.md covers local dev, IA, voice and style, and PR conventions - README's contributing section now points at the dedicated doc --- .github/dependabot.yml | 16 ++++++++ .github/workflows/ci.yml | 22 +++++++++++ CONTRIBUTING.md | 83 ++++++++++++++++++++++++++++++++++++++++ README.md | 2 +- 4 files changed, 122 insertions(+), 1 deletion(-) create mode 100644 .github/dependabot.yml create mode 100644 .github/workflows/ci.yml create mode 100644 CONTRIBUTING.md diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..c5d2b54 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,16 @@ +version: 2 +updates: + - package-ecosystem: npm + directory: "/" + schedule: + interval: weekly + open-pull-requests-limit: 5 + groups: + astro: + patterns: + - "astro" + - "@astrojs/*" + - package-ecosystem: github-actions + directory: "/" + schedule: + interval: weekly diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..e863c9a --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,22 @@ +name: CI + +on: + pull_request: + push: + branches: [main] + +permissions: + contents: read + +jobs: + build: + name: Build + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + - uses: actions/setup-node@v5 + with: + node-version: 24 + cache: npm + - run: npm ci + - run: npm run build diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e9d7265 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,83 @@ +# Contributing to the Ordo documentation + +Thanks for considering a contribution. This repository holds the source for the Ordo documentation site at `docs.ordo.ephyrasoftware.com`. The site itself is built with [Astro](https://astro.build/) and the [Starlight](https://starlight.astro.build/) docs theme. + +## What kinds of contributions are welcome + +- Typo and grammar fixes +- Clarifications where a page is confusing or ambiguous +- Missing details (a flag, an option, an edge case) that would have saved you time +- New examples or recipes for things Ordo supports +- New pages that fit the existing information architecture (see below) + +For larger changes — new sections, restructured navigation, significant rewrites — please open an issue first so the direction can be agreed before you invest the time. Small fixes can go straight to a pull request. + +If something on the docs site is wrong because Ordo itself behaves differently than documented, that is a bug worth filing against [`EphyraSoftware/ordo`](https://github.com/EphyraSoftware/ordo) rather than a docs change. Use your judgement; if you are unsure, file the issue here and we will route it. + +## Local development + +```sh +git clone https://github.com/EphyraSoftware/ordo-docs +cd ordo-docs +npm install +npm run dev +``` + +The dev server runs at `http://localhost:4321` with hot reload. To produce a production build: + +```sh +npm run build +``` + +The output is written to `dist/`. CI runs the same build on every pull request. + +## Information architecture + +The site has four top-level sections: + +| Section | Audience and intent | +|---|---| +| Getting Started | A first-time operator following a guided walkthrough | +| Concepts | Short prose pages tying terminology to behaviour | +| Reference | CLI, API, state file format, and configuration — exhaustive, lookup-oriented | +| Architecture | Operator-facing explanation of how the orchestrator and agents fit together | + +When adding a page, decide which section it belongs in based on intent: + +- **Walkthrough or worked example** → Getting Started +- **"What does X mean?"** → Concepts +- **"What flags does this command accept?"** → Reference +- **"How does this fit together?"** → Architecture + +If a page does not fit any section, that is a signal to discuss the structure in an issue rather than to add a new section directly. + +## Voice and style + +Documentation in this repository aims to be: + +- **Concise.** Short paragraphs. One idea per paragraph. Cut words that do not change the meaning. +- **Direct.** Tell the reader what to do or what something means. Avoid hedging like "you might want to consider". +- **Present tense, second person.** "Run `ordo init`." rather than "You will need to run `ordo init`." +- **Scannable.** Use headings, lists, and tables when they help. Do not use them for decoration. +- **British English** for original prose. American English from upstream sources (error messages, third-party tool names) stays as it appears in those sources. + +Code samples should be runnable as written, with placeholders clearly marked (``, ``). + +## Sidebar configuration + +The sidebar is configured in [`astro.config.mjs`](./astro.config.mjs). Each top-level section is currently a single page; as subpages are added, convert the section's entry from a single link into a group with `autogenerate: { directory: '
' }` (Starlight will pick up files automatically) or hand-listed `items` (when ordering matters). + +## Pull request conventions + +- Branch names use kebab-case and reflect the change: `fix/typo-in-tags-page`, `docs/add-drift-recipe`. +- Commits follow [Conventional Commits](https://www.conventionalcommits.org/): `docs:`, `fix:`, `chore:`, `refactor:`, etc. The PR title should also follow this convention. +- For amendments after review, use fixup commits (`git commit --fixup=`) and autosquash before merge rather than amending in place. +- Do not add `Co-Authored-By` lines to commits. + +## What CI checks + +Every pull request runs `npm ci` followed by `npm run build`. The build must pass before a PR can merge. Broken internal links, invalid frontmatter, and missing referenced content all fail the build. + +## License + +By contributing, you agree that your contributions are licensed under the same terms as this repository. diff --git a/README.md b/README.md index f59550b..b53812e 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,6 @@ The sidebar is configured in `astro.config.mjs`. As subpages are added under eac ## Contributing -Spotted a typo, a confusing page, or a missing detail? Pull requests are welcome. Small fixes do not need a prior issue — open a PR directly. For larger changes, open an issue first so the direction can be agreed before you invest the time. +Spotted a typo, a confusing page, or a missing detail? See [`CONTRIBUTING.md`](./CONTRIBUTING.md). Small fixes can go straight to a pull request; larger changes start with an issue. The Ordo project itself lives at [`EphyraSoftware/ordo`](https://github.com/EphyraSoftware/ordo). From 8e3432f04ea000130b69864f1ba2bf00aec91edc Mon Sep 17 00:00:00 2001 From: synchwire Date: Sun, 26 Apr 2026 00:43:08 +0100 Subject: [PATCH 2/2] fix: remove links to private ordo repository The main ordo repository is private; linking to it from the public docs site produced 404s for unauthenticated visitors. Drop the landing-page GitHub CTA, the README footer reference, and the bug-routing instruction in CONTRIBUTING.md until the main repository is made public. --- CONTRIBUTING.md | 2 +- README.md | 2 -- src/content/docs/index.mdx | 4 ---- 3 files changed, 1 insertion(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e9d7265..e0852e9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,7 +12,7 @@ Thanks for considering a contribution. This repository holds the source for the For larger changes — new sections, restructured navigation, significant rewrites — please open an issue first so the direction can be agreed before you invest the time. Small fixes can go straight to a pull request. -If something on the docs site is wrong because Ordo itself behaves differently than documented, that is a bug worth filing against [`EphyraSoftware/ordo`](https://github.com/EphyraSoftware/ordo) rather than a docs change. Use your judgement; if you are unsure, file the issue here and we will route it. +If something on the docs site is wrong because Ordo itself behaves differently than documented, file an issue here describing what you observed and what the docs led you to expect. We will route it to the right place. ## Local development diff --git a/README.md b/README.md index b53812e..586d1b5 100644 --- a/README.md +++ b/README.md @@ -37,5 +37,3 @@ The sidebar is configured in `astro.config.mjs`. As subpages are added under eac ## Contributing Spotted a typo, a confusing page, or a missing detail? See [`CONTRIBUTING.md`](./CONTRIBUTING.md). Small fixes can go straight to a pull request; larger changes start with an issue. - -The Ordo project itself lives at [`EphyraSoftware/ordo`](https://github.com/EphyraSoftware/ordo). diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 780f99d..7cf3205 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -8,10 +8,6 @@ hero: - text: Get started link: /getting-started/ icon: right-arrow - - text: View on GitHub - link: https://github.com/EphyraSoftware/ordo - icon: external - variant: minimal --- import { Card, CardGrid } from '@astrojs/starlight/components';