From 877c973e87328ba945b55aa07fdeb8ce51f68dad Mon Sep 17 00:00:00 2001 From: Rootiest Date: Mon, 31 Aug 2026 23:16:41 -0400 Subject: [PATCH] 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. --- .github/ISSUE_TEMPLATE/{bug.yaml => bug.yml} | 10 ++++++- .../{config.yaml => config.yml} | 10 ++++++- CONTRIBUTING.md | 29 +++++++++++++++++++ 3 files changed, 47 insertions(+), 2 deletions(-) rename .github/ISSUE_TEMPLATE/{bug.yaml => bug.yml} (89%) rename .github/ISSUE_TEMPLATE/{config.yaml => config.yml} (55%) diff --git a/.github/ISSUE_TEMPLATE/bug.yaml b/.github/ISSUE_TEMPLATE/bug.yml similarity index 89% rename from .github/ISSUE_TEMPLATE/bug.yaml rename to .github/ISSUE_TEMPLATE/bug.yml index fe1fdde..c3cff4c 100644 --- a/.github/ISSUE_TEMPLATE/bug.yaml +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -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: diff --git a/.github/ISSUE_TEMPLATE/config.yaml b/.github/ISSUE_TEMPLATE/config.yml similarity index 55% rename from .github/ISSUE_TEMPLATE/config.yaml rename to .github/ISSUE_TEMPLATE/config.yml index de6c3ee..c041d6e 100644 --- a/.github/ISSUE_TEMPLATE/config.yaml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8382bf7..7dd34fa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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/):