| name | nethserver-issue |
| description | Write well-structured GitHub issues following NethServer contribution guidelines. Use when the user asks to open an issue, file a bug report, request a feature, or mentions "/issue". Supports: (1) Bug report template with component, reproduction steps, and expected behavior, (2) Feature request template with user value and references, (3) Issue type selection (Bug/Feature/Design/Backend/Frontend/Task/Draft), (4) Label guidance (testing, verified, milestone goal), (5) Security vulnerability reporting rules and correct tracker URLs |
NethServer Issue Writing Guidelines
Overview
Write clear, actionable GitHub issues following NethServer project conventions.
Source: NethServer Development Handbook — Issues
Before opening an issue
Issues are not a to-do list. Open an issue only when you are ready to produce a formal output (code change, new container image, package). If you are exploring an idea or hunting a hard-to-reproduce bug, open a community discussion first:
Create an issue once the problem is confirmed and the work can be formally described.
Issue types
Choose the correct type when opening an issue:
| Type | When to use |
|---|
| Bug | A defect that must be fixed (e.g., a process crashes, a feature behaves incorrectly) |
| Feature | An improvement or new capability (e.g., new UI panel, new API endpoint) |
| Design | UI/UX design work; output is a mockup (Figma, image) |
| Backend | Backend implementation sub-task (API, package update, service logic) |
| Frontend | Frontend implementation sub-task (UI panel, page) |
| Task | Specific work item that is not a bug or feature (refactoring, documentation) |
| Draft | Idea not yet ready for development; used for backlog planning |
Sub-issues (Backend, Frontend, Design, Task) are children of a parent Bug or Feature issue.
QA testing targets the parent issue, not sub-issues.
Writing a bug report
Use the Bug type. Include all of the following:
## Component and version
<Name of the affected component and its version, e.g., "nethserver-mail 3.2.1">
## Steps to reproduce
1. <First step>
2. <Second step>
3. ...
## Expected behavior
<What should happen>
## Actual behavior
<What actually happens — describe the error clearly>
## Suggested fix or workaround
<Optional: any ideas on what may cause it or how to fix it>
## Relevant logs or output
<Paste relevant log lines, command output, or screenshots>
Tips:
- Be precise about the version — bugs are often version-specific.
- Include the minimal steps to reproduce reliably.
- Good text formatting and screenshots make the report much more useful.
Writing a feature request
Use the Feature type. Include all of the following:
## Description
<Describe the feature in plain language that anyone can understand.
Use examples to illustrate the use case.>
<Explain who benefits from this and why it matters.>
## Alternative solutions
<Describe any alternative approaches you considered and why you rejected them.>
## References
<Links to external documentation, related projects, or prior discussions.>
Tips:
- Avoid technical jargon; describe the feature from the user's perspective.
- Images and mockups make feature requests much easier to evaluate.
- Link to any community discussion where this was already debated.
Where to file issues
Never report security vulnerabilities as public GitHub issues.
Use the GitHub Security Advisory form or email sviluppo@nethesis.it.
