docs(contributing): make the issue templates work on the GitHub mirror too

The templates were written against Gitea's schema alone, but the mirror
serves the same .github/ISSUE_TEMPLATE/ files to GitHub, where two of them
would have silently failed:

- **config.yaml -> config.yml.** Gitea accepts either spelling
  (modules/structs/issue.go: `base == "config.yaml" || base == "config.yml"`),
  GitHub only recognizes config.yml. Under the old name the mirror's
  template chooser would have shown neither the contact links nor the
  blank-issue setting.
- **bug.yaml `about:` -> bug.yml `description:`.** GitHub requires
  `description` on a YAML issue form; Gitea's IssueTemplate.About carries
  the comment "Using description in a template file is compatible" and
  falls back to it at modules/issue/template/unmarshal.go:126. So
  `description` is the one spelling both forges accept. The markdown
  templates keep `about:`, which is correct for their format on both.

Both files now carry a comment explaining the constraint, so neither gets
"tidied" back into a broken state.

Also add a contact link pointing at the canonical Gitea tracker, so someone
arriving from the mirror is steered to the right place before they file,
and document mirror parity in CONTRIBUTING.md: the labels must be created
on both sides by hand, since mirroring copies files rather than repository
settings and GitHub drops a labels: entry naming a label it doesn't have.
Note too that GitHub has no exclusive labels, so the one-of rule on
Priority/, Reviewed/, and Status/ holds only by convention there.
This commit is contained in:
2026-08-31 23:16:41 -04:00
parent ce3c44a053
commit 877c973e87
3 changed files with 47 additions and 2 deletions
@@ -1,5 +1,13 @@
# The key below is `description`, NOT `about`.
#
# GitHub requires `description` on a YAML issue form and rejects the
# template without it; Gitea wants `about` but explicitly accepts
# `description` as a compatible alias. `description` is therefore the
# only spelling that works on both the canonical repo and the mirror.
# The markdown templates beside this one still use `about`, which is
# correct for their format on both forges.
name: Bug report
about: Something in the config is broken or behaves unexpectedly
description: Something in the config is broken or behaves unexpectedly
labels:
- Kind/Bug
body:
@@ -1,10 +1,18 @@
# Gitea reads this alongside the templates in this directory.
# Read by both Gitea (the canonical repo) and GitHub (the mirror).
#
# The .yml extension is required: Gitea accepts config.yaml or config.yml,
# but GitHub only recognizes config.yml and silently ignores config.yaml.
# Don't "tidy" this back to .yaml — the chooser on the mirror stops working.
#
# Blank issues stay enabled deliberately: the three templates cover bugs,
# features, and docs, and anything else (a chore, a refactor, a question)
# is better served by an empty box than by a template that doesn't fit.
blank_issues_enabled: true
contact_links:
- name: Canonical repository and issue tracker
url: https://git.rootiest.dev/rootiest/fish-config/issues
about: fish-config is developed on Gitea. If you came from the GitHub mirror, please file here instead — the mirror is read-only and issues opened there are easy to miss.
- name: Contributing guide
url: https://git.rootiest.dev/rootiest/fish-config/src/branch/main/CONTRIBUTING.md
about: Branch naming, commit conventions, coding standards, and the label taxonomy.
+29
View File
@@ -56,6 +56,13 @@ refuses to submit without them. The other two are markdown templates in the
same comment-guided style as `.github/PULL_REQUEST_TEMPLATE.md`, since what
they ask for is open-ended prose that structure would only get in the way of.
GitHub reads these same files on the mirror, and its schema differs from
Gitea's in two places, so both are pinned to the spelling that works on both
and each file says so in a comment: the chooser config must be `config.yml`
(GitHub ignores `config.yaml`), and `bug.yml` declares `description:` rather
than `about:` (GitHub requires it; Gitea accepts it as an alias). The two
markdown templates keep `about:`, which is correct for their format on both.
### Issue titles
**Issue titles are plain descriptions of the problem, not Conventional
@@ -283,6 +290,28 @@ Use `good first issue` for work that is genuinely self-contained — a clear
acceptance criterion, one or two files, no need to understand the
opinionated-component system first.
### The GitHub mirror
The repo is mirrored to
[github.com/rootiest/fish-config](https://github.com/rootiest/fish-config),
and **the mirror carries the same labels, by the same names**. That isn't
cosmetic: GitHub reads the same `.github/ISSUE_TEMPLATE/` files, and a
`labels:` entry naming a label that doesn't exist on that side is silently
dropped rather than reported. Mirroring copies files, not repository
settings, so **a label added here must be created on the mirror too** — no
automation does it for you.
One behavioral difference to keep in mind: **GitHub has no exclusive
labels.** Gitea enforces one-at-a-time on `Priority/`, `Reviewed/`, and
`Status/` by swapping the old label out; on the mirror those are ordinary
labels and nothing stops two of a group coexisting, so there the one-of rule
holds by convention alone.
Issues and pull requests belong on the canonical Gitea repo — the template
chooser links there first, on both sides. The mirror's tracker stays open so
that a report which lands there anyway isn't lost, not because it's a second
supported front door.
## Commit Conventions
Commit subjects follow [Conventional Commits](https://www.conventionalcommits.org/):