Skip to content

Update maintainer_guide.md to v2 — workflow, philosophy, and translation banners #4597

@Syknapse

Description

@Syknapse

What needs updating

`maintainer_guide.md` describes the old v1 manual workflow (reviewing PRs by hand, resolving merge conflicts, using GitKraken). The project is now on v2 — card submissions are fully automated. The guide is misleading to any new maintainer.

The file also ends with dangling stub text that was never removed (`Paste this into the file`, `Commit message:`, `PR description:` with no content).

What the update should include

Remove the v1 workflow sections:

  • Manual PR review checklist (the bot handles this)
  • Merge conflict resolution for cards (archiving eliminates this)
  • GitKraken / local tooling recommendation for card merges
  • The trailing stub text

Add v2 workflow section:

  • Overview of the automated pipeline (validate → automerge → archive)
  • What a maintainer actually does now: approve ci.yml workflows for flagged contributors, handle `Remove Card` requests via GitHub Actions, monitor the Actions tab for failed archive runs and re-trigger manually if needed
  • Link to `archive/README.md` for archive operations

Add project philosophy section (matching the principles in `CLAUDE.md`):

  • Contributors first
  • Minimum maintainability
  • Simplicity — no over-engineering

Translation files

All translation files in `translations/maintainer_guide/` describe the v1 workflow and are now outdated. Two tasks:

  1. Add an outdated banner to the top of every translation file (same pattern as README translations):

```markdown

⚠️ This translation is outdated.
It describes the old v1 manual workflow. The project now uses automated validation and merging (v2).
Please refer to the English maintainer guide for current instructions.
```

  1. Update the language table in `maintainer_guide.md` to note that translations are currently outdated.

This is a good first contribution for a maintainer who wants to help — translating the updated guide into their language once the English version is updated.

Notes

Do not attempt to re-translate the full guide — translations are community-maintained. The English guide update + outdated banners on translations is the scope.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions