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
|
name: Bug report
|
||||||
about: Something in the config is broken or behaves unexpectedly
|
description: Something in the config is broken or behaves unexpectedly
|
||||||
labels:
|
labels:
|
||||||
- Kind/Bug
|
- Kind/Bug
|
||||||
body:
|
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,
|
# Blank issues stay enabled deliberately: the three templates cover bugs,
|
||||||
# features, and docs, and anything else (a chore, a refactor, a question)
|
# 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.
|
# is better served by an empty box than by a template that doesn't fit.
|
||||||
blank_issues_enabled: true
|
blank_issues_enabled: true
|
||||||
|
|
||||||
contact_links:
|
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
|
- name: Contributing guide
|
||||||
url: https://git.rootiest.dev/rootiest/fish-config/src/branch/main/CONTRIBUTING.md
|
url: https://git.rootiest.dev/rootiest/fish-config/src/branch/main/CONTRIBUTING.md
|
||||||
about: Branch naming, commit conventions, coding standards, and the label taxonomy.
|
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
|
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.
|
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
|
||||||
|
|
||||||
**Issue titles are plain descriptions of the problem, not Conventional
|
**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
|
acceptance criterion, one or two files, no need to understand the
|
||||||
opinionated-component system first.
|
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 Conventions
|
||||||
|
|
||||||
Commit subjects follow [Conventional Commits](https://www.conventionalcommits.org/):
|
Commit subjects follow [Conventional Commits](https://www.conventionalcommits.org/):
|
||||||
|
|||||||
Reference in New Issue
Block a user