Syknapse / Syknapse/Contribute-To-This-Project

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

Open
#4,597 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation
Dominant language
JavaScript
Stars
2.6k
Forks
3.5k
Avg merge
13h 14m
Merged PRs (30d)
32

Description

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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with maintainer_guide.md, CLAUDE.md, archive/README.md, and the README translation banners for the current principles, archive workflow, and banner pattern. Update the English guide, language table, and every file under translations/maintainer_guide/ without re-translating them. Done means the v1 instructions and stub text are removed, the v2 workflow and philosophy are documented, and all translations clearly point readers to the English guide.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, markdown
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.