Reporting bugs well #

This page is for advocates who report bugs and who help others report them. A good report is the fastest way to get a problem fixed for everyone. The project's own guidance is in When something goes wrong, A good bug description; this page turns it into a routine.

Contents #

1. Before you file
2. The parts of a good report
3. The template
4. Getting the environment safely
5. Reviewing someone else's report
6. After filing

Before you file #

1. Is it a bug, or a question? Questions go to the forums (Which tracker for which report).
2. Is it a security problem? Then private (Security reports stay private).
3. Search the tracker; if it exists, add what you know there.
4. Can you reproduce it on a fresh installation? If not, it may be the site's own setup.
5. Is it really wrong, or deliberate and open to interpretation? A negative feature is behavior other sites depend on; a report asking to change it needs a clear justification and patience through several rounds of review.

The parts of a good report #

The title example comes from When something goes wrong.

The template #

Title: <Where>: <what goes wrong>

Steps to reproduce
1. ...
2. ...

Expected
...

Actual
... (exact message, screenshot with invented data)

Environment
Exponential <version or commit>, PHP <version>, <Velocity | FrankenPHP | Apache/nginx + PHP-FPM>,
<database>, <admin4 | classic | AdminUI>

Logs (private data removed)
...

Notes
Reproduced on a fresh installation: <yes/no>. Related: <links>.

Getting the environment safely #

• The Report an error page of the help (exphelp/report) fills in a summary of the installation.
• Setup > System information, Copy report as text, gives the same summary.
• Both leave out passwords, keys and server paths (When something goes wrong).
• Remove IP addresses, e-mail addresses and names from logs before posting.

Reviewing someone else's report #

Help a reporter improve their issue with a friendly comment:

[ ] Can I follow the steps? If not, ask for the missing one
[ ] Is the exact message there?
[ ] Is the environment there?
[ ] Is there anything private in it? (then ask them to edit it out at once)
[ ] Can I reproduce it? (then say so, with my environment)

See Reproducing and confirming issues.

After filing #

• Answer questions on the issue promptly.
• If you find the cause, consider sending the fix (Even better: send the fix).
• When it is fixed, thank the people involved.

Related pages #

• Which tracker for which report
• Reproducing and confirming issues
• GitHub for advocates
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.