From f9557c21154a6c8acfbadde64d28d8bfe1902e68 Mon Sep 17 00:00:00 2001 From: Rafael Vuijk Date: Fri, 2 Oct 2026 20:39:48 +0000 Subject: [PATCH] Instructions for an agent maintaining the site AGENTS.md says how the site is built and published, what a release of the library owes it, and the working practice, which is the library's. CLAUDE.md points to it. The README said the site is generated on a push to gh-pages; it is generated on a push to master and published there. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_012sonx8iAspMiwRwokT1Ura --- AGENTS.md | 41 +++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 4 ++++ README.md | 2 +- 3 files changed, 46 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..3587a94a9 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,41 @@ +# Working in this repository + +This is the source of [am.angouri.org](https://am.angouri.org), the website of +[AngouriMath](https://github.com/asc-community/AngouriMath). An agent maintaining it works as it does +in the library's repository, whose [AGENTS.md](https://github.com/asc-community/AngouriMath/blob/master/AGENTS.md) +sets the working practice for both. When there is nothing to do here, it goes back to the library. + +## How the site is built and published + +- `dotnet fsi amsite.fsx init` clones three things into `src/`: AngouriMath, whose XML documentation + becomes the `/docs` pages through Yadg.NET; Yadg.NET; and the library's wiki, which becomes `/wiki`. + `build` runs `src/NaiveStaticGenerator`, which wraps every page in `src/content` in + `src/content/_templates/top.html` and `bottom.html` and writes `.output/final`. `run` builds and + opens the home page. +- `.output/final` also gets the stylesheets, `img/`, `CNAME`, `robots.txt` and a `sitemap.xml` that + the generator writes from the pages it produced. +- A pull request builds the site on Windows, Linux and macOS (`build-test.yml`). +- **A merge to master is live.** `deployment.yml` builds the site and pushes `.output/final` to the + `gh-pages` branch, and GitHub Pages publishes it a few minutes later. Check the live page after a + merge, not only the workflow. +- The `/docs` and `/wiki` pages are built from the library's master and wiki at deployment time, so a + fix to either reaches the site at the next deployment of this repository. + +## What a release of the library owes the site + +The library's release checklist names it. The *What's new* page gets a block for the release, with +the link to `BREAKING-CHANGES.md` pinned to the release's tag, and the quickstart names the release. +The library's `docsamples` harness, run in its CI with this repository checked out, checks that every +code sample here compiles, runs and prints what its page says. Its report is the place to look before +editing a sample. + +## Working practice + +- One change per pull request, branched from master. Build it locally and look at the page it + changes: a screenshot from a headless browser is enough. +- Read both comment endpoints of a pull request before merging it. The thread is not part of the + checks. +- Load nothing from a third-party domain that a page does not need. A script from a domain the site + does not control runs whatever that domain's next owner serves, which is why polyfill.io went (#36). +- Issues here carry the organisation's issue types and a milestone named after the library's + version, as the library's do. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..9cf4e618a --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,4 @@ +# CLAUDE.md + +The instructions for this repository are in **[AGENTS.md](AGENTS.md)**. Read it before doing +anything else here; this file exists only so that tools looking for `CLAUDE.md` find their way there. diff --git a/README.md b/README.md index c609a5c9d..48dfa39a9 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ This repo contains all the files for the website of [AngouriMath](https://github.com/asc-community/AngouriMath). -The master branch only contains files necessary for the generation itself. The generation happens automatically on every push to gh-pages branch. The content of the website is located at `src/content`. +The master branch only contains files necessary for the generation itself. Every push to master generates the website and publishes it to the gh-pages branch, which GitHub Pages serves. The content of the website is located at `src/content`. There's a custom generator which wraps the content files with the given templates, which are located at `src/content/_templates`.