Skip to content

Docs, standards and community hygiene sweep: ghost references, EN-only root files, container and contribution surfaces (from the #964 review) #970

Open

Description

@cemililik

A sweep of small documentation, standards and community-surface items found while reviewing #964. Each is one line of reasoning and a minute of work; they are grouped so the backlog gains one item rather than a dozen.

Ghost and stale references

  • CODE_OF_CONDUCT.md:33 points at a Discord channel that appears nowhere else in the repository. Either name the invite route or drop the reference — a conduct page should not send a reporter to a channel that may not exist.
  • docs/roadmap/risks-and-decisions.md carries a Turkish heading inside an otherwise English file. Decide the file's language and make it consistent.

Standards should name the new root surfaces

  • docs/standards/documentation.md and docs/standards/localization.md do not say what the new root files are (GOVERNANCE.md, MAINTAINERS.md, CITATION.cff, .github/CODEOWNERS, .github/dependabot.yml). Say explicitly that they are contributor-facing and English-only, the same way CONTRIBUTING.md, SECURITY.md and CODE_OF_CONDUCT.md are — otherwise the next reviewer has to re-derive it.
  • .dockerignore does not list the new root files. Check whether they belong in the build context.

Dependency and supply-chain prose

  • docs/reference/supply_chain_security.md does not mention Dependabot. Now that .github/dependabot.yml exists, name it as the update channel alongside check_pip_audit.py and the nightly CVE job.
  • .github/dependabot.yml does not say why it has no cooldown, no timezone, and no docker/npm ecosystems. A one-line comment prevents each being re-litigated.

Contribution surfaces

  • CONTRIBUTING.md does not state the "an issue is the unit of work" rule; it lives only in GOVERNANCE.md. A contributor reads CONTRIBUTING.md first.
  • GOVERNANCE.md does not mention the licence or whether contributions carry a sign-off (DCO). Say which, or say explicitly that none is required.
  • SUPPORT.md does not exist. GitHub's community profile expects one, and it is the natural place to route "a question" versus "a bug" versus "a security report".
  • There is no stated policy on AI-assisted contributions. The project uses AI tooling heavily itself, so a short disclosure line is more honest than silence — decide whether disclosure is required, encouraged, or not expected.

Roadmap mechanism

  • GOVERNANCE.md says a change larger than one issue "becomes a roadmap phase under docs/roadmap/". The repository's actual grouping mechanism is the epic label plus sub-issues. Reconcile the two sentences.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area: dev-toolingCode area: dev-toolingdocumentationImprovements or additions to documentationseverity: lowMinor defect, inaccuracy or rough edgewave: 4Roadmap wave 4: low / info / watch, when touching the module

    Type

    No type

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions