Differential D25007 Diff 21 src/docs/contributor/bug_reports.diviner

Changeset View

Standalone View

View Options

src/docs/contributor/bug_reports.diviner

@title Contributing Bug Reports

@group detail

Effective June 1, 2021: Phabricator is no longer actively maintained and no longer accepts bug reports.

Describes how to file an effective Phorge bug report.

Overview

========

This article describes how to file an effective Phorge bug report.

The most important things to do are:

- check the list of common fixes below;

- make sure Phorge is up to date;

- make sure we support your setup;

- gather debugging information; and

- explain how to reproduce the issue.

The rest of this article walks through these points in detail.

For general information on contributing to Phorge, see

@{article:Contributor Introduction}.

Common Fixes

============

Before you file a report, here are some common solutions to problems:

- **Update Phorge**: We receive a lot of bug reports about issues we have

already fixed in HEAD. Updating often resolves issues. It is common for

issues to be fixed in less than 24 hours, so even if you've updated recently

you should update again. If you aren't sure how to update, see the next

section.

- **Update Libraries**: Make sure `arcanist/` and `phorge/` are all up

to date. Users often update `phorge/` but forget to update `arcanist/`.

When you update, make sure you update both libraries.

- **Restart Apache or PHP-FPM**: Phorge uses caches which don't get

reset until you restart Apache or PHP-FPM. After updating, make sure you

restart.

Update Phorge

=============

Before filing a bug, make sure you are up to date. We receive many bug reports

for issues we have already fixed, and even if we haven't fixed an issue we'll

be able to resolve it more easily if you file a report based on HEAD. (For

example, an old stack trace may not have the right line numbers, which will

make it more difficult for us to figure out what's going wrong.)

To update Phorge, use a script like the one described in

@{article:Upgrading Phorge}.

**If you can not update** for some reason, please include the version of

Phorge and Arcanist you are running when you file a report.

For help, see @{article:Providing Version Information}.

Supported Issues

================

Before filing a bug, make sure you're filing an issue against something we

support.

**We can NOT help you with issues we can not reproduce.** It is critical that

you explain how to reproduce the issue when filing a report.

For help, see @{article:Providing Reproduction Steps}.

**We do NOT support prototype applications.** If you're running into an issue

with a prototype application, you're on your own. For more information about

prototype applications, see @{article:User Guide: Prototype Applications}.

**We do NOT support third-party packages or instructions.** If you installed

Phorge (or configured some aspect of it) using a third-party package or by

following a third-party guide (like a blog post), we can not help you.

Phorge changes quickly and third-party information is unreliable and often

falls out of date. Contact the maintainer of the package or guide you used,

or reinstall following the upstream instructions.

**We do NOT support custom code development or third-party libraries.** If

you're writing an extension, you're on your own. We provide some documentation,

but can not help you with extension or library development. If you downloaded a

library from somewhere, contact the library maintainer.

**We do NOT support bizarre environments.** If your issue is specific to an

unusual installation environment, we generally will not help you find a

workaround. Install Phorge in a normal environment instead. Examples of

unusual environments are shared hosts, nontraditional hosts (gaming consoles,

storage appliances), and hosts with unusually tight resource constraints. The

vast majority of users run Phorge in normal environments (modern computers

with root access) and these are the only environments we support.

Otherwise, if you're having an issue with a supported first-party application

and followed the upstream install instructions on a normal computer, we're happy

to try to help.

Getting More Information

========================

For some issues, there are places you can check for more information. This may

help you resolve the issue yourself. Even if it doesn't, this information can

help us figure out and resolve an issue.

- For issues with `arc` or any other command-line script, you can get more

details about what the script is doing by adding the `--trace` flag.

- For issues with Phorge, check your webserver error logs.

- For Apache, this is often `/var/log/httpd/error.log`, or

`/var/log/apache2/error.log` or similar.

- For nginx, check both the nginx and php-fpm logs.

- For issues with the UI, check the Javascript error console in your web

browser.

- Some other things, like daemons, have their own debug flags or

troubleshooting steps. Check the documentation for information on

troubleshooting. Adjusting settings or enabling debugging modes may give

you more information about the issue.

Reproducibility

===============

The most important part of your report content is instructions on how to

reproduce the issue. What did you do? If you do it again, does it still break?

Does it depend on a specific browser? Can you reproduce the issue on

a fresh, unmodified Phorge instance?

chrisUnsubmitted

Done

Does it depend on a specific browser? Can you reproduce the issue on

- [[ https://demo.phorge.it | our test instance]]?

+ a fresh, unmodified Phorge instance?

It is nearly impossible for us to resolve many issues if we can not reproduce

Maybe omit this until we set this up to avoid confusion?

chris: Maybe omit this until we set this up to avoid confusion?

It is nearly impossible for us to resolve many issues if we can not reproduce

them. We will not accept reports which do not contain the information required

to reproduce problems.

For help, see @{article:Providing Reproduction Steps}.

File a Bug Report

=================

If you're up to date, have collected information about the problem, and have

the best reproduction instructions you can come up with, you're ready

to file a report.

It is **particularly critical** that you include reproduction steps.

You can file a report [[ https://we.phorge.it/maniphest/task/edit/form/2/ | on this instance]].

Lint: Line Too Long

This line is 95 characters long, but the convention is 80 characters.

Lint: Line Too Long: This line is 95 characters long, but the convention is 80 characters.

Next Steps

==========

Continue by:

- reading general support information in @{article:Support Resources}; or

- returning to the @{article:Contributor Introduction}.