GitHub mirror: a README notice shown only on GitHub, pointing to the official repository #938

New issue

Closed

opened 2026-10-16 13:47:35 +00:00 by tiagoagueda · 0 comments

tiagoagueda commented

2026-10-16 13:47:35 +00:00

Owner

How: the two forges pick a README differently

GitHub shows .github/README.md first. Its order is the .github/ folder, then the root, then docs/ (GitHub docs, About READMEs; confirmed in practice here).
Forgejo shows the root README.md. It looks in docs/, .gitea/ or .github/ only when the root has none (the change that added the fallback).

So a .github/README.md in the repository changes only what GitHub shows. It travels with every mirror push like any other file. Confirm Forgejo's order against the running version before relying on it.

What would change

Generate .github/README.md from README.md, never by hand. A small script (scripts/github_readme.py, or a pre-commit step) writes it as:
- the notice at the top, for example: "This is a read-only mirror. Postulo is developed at source.tiagoagueda.com/postulo/postulo. Please open issues, suggestions and pull requests there.";
- then the whole root README.
The notice is in English, like the rest of the README.
Rewrite the relative links. GitHub resolves relative links from the README file's own folder, so src/postulo/static/brand/logo-256.png or CHANGELOG.md would break from .github/. The script rewrites them either to ../… or to absolute links on Forgejo. Absolute links are better: they also send readers to the official repository.
Check it in CI. A test (or a check in the existing lint job) fails when .github/README.md differs from what the script would write, the way messages.py extract --check keeps the catalogues current. A README change then can't land without the mirror's copy.
GitHub settings, set once by hand and written down in CONTRIBUTING.md:
- turn off Issues, Wiki, Projects and Discussions;
- set the description and website to the Forgejo URL.
- Pull requests can't be turned off. Optionally, a GitHub-only workflow closes new ones with a pointer to Forgejo (see the caution below).
Document the mirror in CONTRIBUTING.md:
- where the code lives and how the mirror is fed;
- that .github/README.md is generated.

Caution: Forgejo also reads `.github/`

Templates. Forgejo falls back to .github/ for issue and pull request templates when .forgejo/ and .gitea/ have none.
Workflows. It falls back to .github/workflows when .forgejo/workflows is missing.
What to do. A README there is harmless. Any GitHub-only template or workflow added later needs its Forgejo counterpart in .forgejo/, so Forgejo never picks up the GitHub one. Add a test that asserts this.

#936 and #937 (README changes). The generated copy picks those up automatically.

Postulo lives on Forgejo and is mirrored to GitHub. On GitHub, and only there, the README should open with a notice that the repository is a read-only mirror, and that issues, suggestions and pull requests belong on the official repository at source.tiagoagueda.com. The mirror should stay a plain, byte-for-byte copy: no separate branch to keep rebased. ## How: the two forges pick a README differently - **GitHub shows `.github/README.md` first.** Its order is the `.github/` folder, then the root, then `docs/` ([GitHub docs, About READMEs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes); confirmed in practice [here](https://zenn.dev/kou_pg_0131/articles/github-readme-path)). - **Forgejo shows the root `README.md`.** It looks in `docs/`, `.gitea/` or `.github/` only when the root has none ([the change that added the fallback](https://git.fb1.uni-bremen.de/davrot/forgejo_backup/commit/ef7fd781f5f5f5812a8a947845afac7a1dba4886)). So a `.github/README.md` in the repository changes only what GitHub shows. It travels with every mirror push like any other file. Confirm Forgejo's order against the running version before relying on it. ## What would change 1. **Generate `.github/README.md` from `README.md`, never by hand.** A small script (`scripts/github_readme.py`, or a pre-commit step) writes it as: - **the notice at the top**, for example: *"This is a read-only mirror. Postulo is developed at [source.tiagoagueda.com/postulo/postulo](https://source.tiagoagueda.com/postulo/postulo). Please open issues, suggestions and pull requests there."*; - **then the whole root README.** The notice is in English, like the rest of the README. 2. **Rewrite the relative links.** GitHub resolves relative links from the README file's own folder, so `src/postulo/static/brand/logo-256.png` or `CHANGELOG.md` would break from `.github/`. The script rewrites them either to `../…` or to absolute links on Forgejo. Absolute links are better: they also send readers to the official repository. 3. **Check it in CI.** A test (or a check in the existing lint job) fails when `.github/README.md` differs from what the script would write, the way `messages.py extract --check` keeps the catalogues current. A README change then can't land without the mirror's copy. 4. **GitHub settings,** set once by hand and written down in CONTRIBUTING.md: - turn off Issues, Wiki, Projects and Discussions; - set the description and website to the Forgejo URL. - Pull requests can't be turned off. Optionally, a GitHub-only workflow closes new ones with a pointer to Forgejo (see the caution below). 5. **Document the mirror** in CONTRIBUTING.md: - where the code lives and how the mirror is fed; - that `.github/README.md` is generated. ## Caution: Forgejo also reads `.github/` - **Templates.** Forgejo falls back to `.github/` for issue and pull request templates when `.forgejo/` and `.gitea/` have none. - **Workflows.** It falls back to `.github/workflows` when `.forgejo/workflows` is missing. - **What to do.** A README there is harmless. Any GitHub-only template or workflow added later needs its Forgejo counterpart in `.forgejo/`, so Forgejo never picks up the GitHub one. Add a test that asserts this. ## Related #936 and #937 (README changes). The generated copy picks those up automatically.

tiagoagueda added the

documentation

label

2026-10-16 13:47:41 +00:00

tiagoagueda referenced this issue

2026-10-16 13:51:52 +00:00

AI assistants: move CLAUDE.md to AGENTS.md, with CLAUDE.md importing it #939

tiagoagueda referenced this issue from a commit

2026-10-17 17:48:29 +00:00

README: badges, a generated language table and a GitHub mirror notice

tiagoagueda referenced this issue from a pull request that will close it,

2026-10-17 17:48:39 +00:00