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

New issue

Closed

opened 2026-10-01 10:29:13 +00:00 by tiagoagueda · 0 comments

tiagoagueda commented

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

Owner

New issue opens an empty box. Somebody reporting a bug has to guess what is needed, and the first reply is usually a question. 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:
- this plugin's version and the Postulo version it runs beside (Server settings → Plugins shows both);
- how the plugin was installed (from the catalogue, from a wheel, built into the image);
- the mail provider or server software, and the language the mail was written in (the classification rules are per 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;
- whether it belongs in this plugin, or needs something from the core's plugin surface first (then the core gets an issue too).
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 this repository

A mail that was classified wrongly is the most useful attachment and the most private one. The form should ask for the subject line and the sender's domain with names removed, not the mail.

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 what is listed above without anybody having to ask.
The forms match the core's wherever the fields are the same.

Requested by the maintainer on 2026-10-01, for every repository. The templates are written in the core first (postulo/postulo#351); this repository takes its own from those, with the fields that differ here. *New issue* opens an empty box. Somebody reporting a bug has to guess what is needed, and the first reply is usually a question. 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: - this plugin's version and the Postulo version it runs beside (*Server settings → Plugins* shows both); - how the plugin was installed (from the catalogue, from a wheel, built into the image); - the mail provider or server software, and the language the mail was written in (the classification rules are per 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; - whether it belongs in this plugin, or needs something from the core's plugin surface first (then the core gets an issue too). - **`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 this repository - A mail that was classified wrongly is the most useful attachment and the most private one. The form should ask for the subject line and the sender's domain with names removed, not the mail. ## 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 what is listed above without anybody having to ask. - The forms match the core's wherever the fields are the same.

tiagoagueda added this to the 0.6.0 milestone

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

tiagoagueda added the

enhancement

documentation

labels

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

tiagoagueda referenced this issue from Postulo/postulo

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

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

tiagoagueda referenced this issue from a pull request that will close it,

2026-11-11 22:44:55 +00:00