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

New issue

Closed

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

tiagoagueda commented

2026-10-01 10:29:17 +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:
- the versions and the client, as listed below;
- 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 is a tool this server should offer, or something the API has to provide 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

The bug form asks for the postulo-mcp version, the Postulo version it talks to, the client (which assistant or tool), and the transport (stdio or HTTP).
An API token is a credential: the form says so above the box where a configuration might be pasted.
What a model did with a tool's answer is usually not this repository's bug; the form should ask for the tool call and its answer, not the conversation.

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: - the versions and the client, as listed below; - 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 is a tool this server should offer, or something the API has to provide 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 - The bug form asks for the postulo-mcp version, the Postulo version it talks to, the client (which assistant or tool), and the transport (stdio or HTTP). - **An API token is a credential**: the form says so above the box where a configuration might be pasted. - What a model did with a tool's answer is usually not this repository's bug; the form should ask for the tool call and its answer, not the conversation. ## 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:17 +00:00

tiagoagueda added the

enhancement

documentation

labels

2026-10-01 10:29:17 +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

2026-10-19 06:50:42 +00:00