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:
@@ -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.
|
||||
@@ -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/):
|
||||
|
||||
Reference in New Issue
Block a user