Issue templates: a form for reporting a bug and a form for asking for a feature

tiagoagueda commented

2026-10-01 10:29:11 +00:00

Owner

Requested by the maintainer on 2026-10-01, for every repository.

New issue opens an empty box here, in every repository of the project. Somebody reporting a bug has to guess what is needed, and the first reply is usually a question: which version, installed how, which browser. A template asks once, at the start.

What to add

Forgejo reads issue templates from the repository itself: files under .forgejo/ISSUE_TEMPLATE/, either Markdown with a small header or YAML forms with typed fields, plus a config.yaml beside them that can switch off blank issues and add links shown above the choices. When templates exist, New issue offers them instead of an empty box.

A bug report (bug.yaml), labelled bug by itself, asking for what a fix needs:
- the version (the foot of every page shows it) or the commit, and how the instance is installed (the published image, a build of one's own, from source);
- the database (SQLite or PostgreSQL);
- the browser and its version, the device, and the interface language;
- what was done, step by step; what happened; what was expected;
- anything from the logs, with personal details removed first. Postulo holds CVs, home addresses and the names of the people somebody is applying to; the form should say so in plain words above the box, because a pasted log or screenshot is where those leak.
A feature request (feature.yaml), labelled enhancement, asking for:
- the problem, and who has it, before the solution;
- what is proposed, and what else was considered;
- which of the project's four commitments it touches (never paywalled, secure, usable by everyone, modular), and whether it could be a plugin rather than part of the core.
config.yaml with links above the two forms:
- A security problem is not a public issue. Link to the core's SECURITY.md, which says how to report one privately. This is the most important line in the whole change: without it the bug form is where a vulnerability gets posted in the open.
- Translations: where to translate (postulo/postulo#349 decides the workflow), so a wrong word is corrected there rather than reported here.
- Questions: wherever the project wants them, if not in issues.
- Whether blank issues stay allowed. The maintainer files long, structured issues by hand; a form must not get in the way of that.

Forms should stay short. A field nobody will read is a reason not to finish the report; every field above is one the fix actually depends on.

For the core

The templates are written here first; the other repositories take theirs from these, changed only where their fields differ. Forgejo reads templates from each repository; unless it turns out to offer a default for a whole organisation, each repository carries its own copy, and something small (a script, or a test in each repository) should say when a copy has drifted from the core's.
CONTRIBUTING.md and the README point at the forms instead of describing what to include.
The repository is mirrored to GitHub. If the mirror's issue tracker is on, a .github/ISSUE_TEMPLATE/config.yml there should send people to Forgejo rather than collect reports in a second place.
The words are English, like every other part of the repository; a reporter writes in whatever language they can, and the form says so.

Done when

New issue on this repository offers Bug report and Feature request, each applying its label, and shows the security link above them.
A report filed through the bug form carries the version, how the instance is installed, the database and the browser without anybody having to ask.
CONTRIBUTING.md names the forms.

The other repositories

Each has the same issue: postulo/postulo-apprise#9, postulo/postulo-dav#18, postulo/postulo-imap#7, postulo/postulo-paperless#9, postulo/postulo-helloworld#8, postulo/postulo-chromium#14, postulo/postulo-thunderbird#11, postulo/postulo-firefox#7, postulo/postulo-templates#11, postulo/postulo-mcp#6.

Requested by the maintainer on 2026-10-01, for every repository. *New issue* opens an empty box here, in every repository of the project. Somebody reporting a bug has to guess what is needed, and the first reply is usually a question: which version, installed how, which browser. A template asks once, at the start. ## What to add Forgejo reads issue templates from the repository itself: files under `.forgejo/ISSUE_TEMPLATE/`, either Markdown with a small header or YAML forms with typed fields, plus a `config.yaml` beside them that can switch off blank issues and add links shown above the choices. When templates exist, *New issue* offers them instead of an empty box. - **A bug report** (`bug.yaml`), labelled `bug` by itself, asking for what a fix needs: - the version (the foot of every page shows it) or the commit, and how the instance is installed (the published image, a build of one's own, from source); - the database (SQLite or PostgreSQL); - the browser and its version, the device, and the interface language; - what was done, step by step; what happened; what was expected; - anything from the logs, **with personal details removed first**. Postulo holds CVs, home addresses and the names of the people somebody is applying to; the form should say so in plain words above the box, because a pasted log or screenshot is where those leak. - **A feature request** (`feature.yaml`), labelled `enhancement`, asking for: - the problem, and who has it, before the solution; - what is proposed, and what else was considered; - which of the project's four commitments it touches (never paywalled, secure, usable by everyone, modular), and whether it could be a plugin rather than part of the core. - **`config.yaml`** with links above the two forms: - **A security problem is not a public issue.** Link to the core's `SECURITY.md`, which says how to report one privately. This is the most important line in the whole change: without it the bug form is where a vulnerability gets posted in the open. - Translations: where to translate (postulo/postulo#349 decides the workflow), so a wrong word is corrected there rather than reported here. - Questions: wherever the project wants them, if not in issues. - Whether blank issues stay allowed. The maintainer files long, structured issues by hand; a form must not get in the way of that. Forms should stay short. A field nobody will read is a reason not to finish the report; every field above is one the fix actually depends on. ## For the core - The templates are written here first; the other repositories take theirs from these, changed only where their fields differ. Forgejo reads templates from each repository; unless it turns out to offer a default for a whole organisation, each repository carries its own copy, and something small (a script, or a test in each repository) should say when a copy has drifted from the core's. - `CONTRIBUTING.md` and the README point at the forms instead of describing what to include. - The repository is mirrored to GitHub. If the mirror's issue tracker is on, a `.github/ISSUE_TEMPLATE/config.yml` there should send people to Forgejo rather than collect reports in a second place. - The words are English, like every other part of the repository; a reporter writes in whatever language they can, and the form says so. ## Done when - *New issue* on this repository offers *Bug report* and *Feature request*, each applying its label, and shows the security link above them. - A report filed through the bug form carries the version, how the instance is installed, the database and the browser without anybody having to ask. - `CONTRIBUTING.md` names the forms. ## The other repositories Each has the same issue: postulo/postulo-apprise#9, postulo/postulo-dav#18, postulo/postulo-imap#7, postulo/postulo-paperless#9, postulo/postulo-helloworld#8, postulo/postulo-chromium#14, postulo/postulo-thunderbird#11, postulo/postulo-firefox#7, postulo/postulo-templates#11, postulo/postulo-mcp#6.

tiagoagueda added this to the 0.6.0 milestone

2026-10-01 10:29:11 +00:00

tiagoagueda added the

labels

2026-10-01 10:29:11 +00:00

tiagoagueda referenced this issue from Postulo/postulo-apprise

2026-10-01 10:29:12 +00:00

Issue templates: a form for reporting a bug and a form for asking for a feature #9