Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: Improve instructions for reporting bugs. 

- Create a dedicated "Reporting bugs" page to learly document
where and how bugs should be reported.
- Drop "Reporting issues" section from the Contributing guide.
- Delete "Bug report guidelines" page.
This commit is contained in:
Alya Abbott 2023-06-12 05:51:03 -07:00
parent bd217ad31b
commit 052a109ba4
6 changed files with 166 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
CONTRIBUTING.md
View File

@ -55,8 +55,7 @@ needs doing:
**Non-code contributions**: Some of the most valuable ways to contribute
don't require touching the codebase at all. For example, you can:
- [Report issues](#reporting-issues), including both feature requests and
bug reports.
- Report issues, including both feature requests and bug reports.
- [Give feedback](#user-feedback) if you are evaluating or using Zulip.
- [Participate
thoughtfully](https://zulip.readthedocs.io/en/latest/contributing/design-discussions.html)
@ -314,29 +313,6 @@ experience, these are the best predictors of success:
[great-questions]: https://zulip.readthedocs.io/en/latest/contributing/asking-great-questions.html
## Reporting issues
If you find an easily reproducible bug and/or are experienced in reporting
bugs, feel free to just open an issue on the relevant project on GitHub.
If you have a feature request or are not yet sure what the underlying bug
is, the best place to post issues is
[#issues](https://chat.zulip.org/#narrow/stream/9-issues) (or
[#mobile](https://chat.zulip.org/#narrow/stream/48-mobile) or
[#desktop](https://chat.zulip.org/#narrow/stream/16-desktop)) on the
[Zulip community server](https://zulip.com/development-community/).
This allows us to interactively figure out what is going on, let you know if
a similar issue has already been opened, and collect any other information
we need. Choose a 2-4 word topic that describes the issue, explain the issue
and how to reproduce it if known, your browser/OS if relevant, and a
[screenshot or screenGIF](https://zulip.readthedocs.io/en/latest/tutorials/screenshot-and-gif-software.html)
if appropriate.
**Reporting security issues**. Please do not report security issues
publicly, including on public streams on chat.zulip.org. You can
email [security@zulip.com](mailto:security@zulip.com). We create a CVE for every
security issue in our released software.
## User feedback
Nearly every feature we develop starts with a user request. If you are part

23
docs/contributing/bug-reports.md
View File

@ -1,23 +0,0 @@
# Bug report guidelines
Please include these elements in your bug report to make it easier for us to help you.
- A brief title
- An explanation of what you were expecting vs. the actual result
- Steps to take in order to reproduce the buggy behavior
- Whether you are using Zulip in production or in the development
environment, and whether these are old versions
- Whether you are using the web app, a desktop app or a mobile device
to access Zulip
- Any additional information that would help: screenshots, GIFs, a
pastebin of the error log
Further reading:
- [How to write a bug report that will make your engineers love you](https://testlio.com/blog/the-ideal-bug-report/)
- [How to Report Bugs Effectively](https://www.chiark.greenend.org.uk/~sgtatham/bugs.html)

2
docs/contributing/index.md
View File

@ -16,6 +16,6 @@ reviewable-prs
code-reviewing
review-process
zulipbot-usage
bug-reports
reporting-bugs
licensing
```

155
docs/contributing/reporting-bugs.md Normal file
View File

@ -0,0 +1,155 @@
# Reporting bugs
The are several ways to report bugs (or possible bugs) you encounter in Zulip.
- If you have a concrete bug report with steps to reproduce the behavior, [file an
issue](#filing-a-github-issue) in the appropriate GitHub repository.
- If you are not sure whether the issue you encountered is a bug, or how to
reproduce it, [start a
conversation](#starting-a-conversation-about-a-possible-bug) in the Zulip
development community.
- To report a possible security issue, contact Zulip's security team at
[security@zulip.com](mailto:security@zulip.com). _Do not_ report security issues
publicly (in GitHub or in the Zulip development community). We create a CVE for
every security issue in our released software.
- If reporting a bug requires sharing private details about your
organization, email [support@zulip.com](mailto:support@zulip.com).
No matter where you report the bug, please follow the instructions below for
what to include in a bug report.
## What to include in a bug report
1. **Describe** what you were expecting to see, what you saw instead, and steps
that may help others reproduce the surprising behavior you experienced.
Include screenshots and/or screen captures (see [recommended
tools](../tutorials/screenshot-and-gif-software.md)) if they help
communicate what you are describing, but avoid posting long videos.
1. Indicate the **[version](https://zulip.com/help/view-zulip-version)** of the
Zulip app where you encountered the bug. It may also be helpful to note your
operating system, whether you are using the web app or the desktop app, and
your browser if using the web app.
## Filing a GitHub issue
Filing a GitHub issue works best when:
- You are confident that the behavior you encountered is a bug, not some quirk
of how a feature works that may turn out to be intentional.
- You can describe clearly what you were expecting to see, and what you saw instead.
- You can provide steps for someone else to reproduce the issue you encountered.
This is important for developers to be able to fix the bug, and test that
their fix worked.
If all of the above accurately describe your situation, please file an issue!
Otherwise, we recommend [starting a
conversation](#starting-a-conversation-about-a-possible-bug) in the Zulip
development community, so that the problem you encountered can be discussed
interactively.
Steps and best practices for filing an issue:
1. Report the issue in the **appropriate [Zulip
repository](https://github.com/zulip)**. The most commonly used repositories
are:
- [zulip/zulip](https://github.com/zulip/zulip/issues) for issues with the
Zulip web app or server. A good default if you aren't sure which repository
to use.
- [zulip/zulip-mobile](https://github.com/zulip/zulip-mobile/issues) for
issues with the mobile apps.
- [zulip/zulip-desktop](https://github.com/zulip/zulip-desktop/issues) for
issues that are specific to the Zulip desktop app, and _do not_ occur in
the web app.
- [zulip/zulip-terminal](https://github.com/zulip/zulip-terminal/issues) for
issues with the terminal app.
2. Do a **quick search** of the repository to see if your issue has already
been filed. If it has, you can add a comment if that seems helpful.
3. If you are aware of a related discussion in the Zulip development community,
please **cross-link** between the issue and the discussion thread. [Link to a
specific
message](https://zulip.com/help/link-to-a-message-or-conversation#get-a-link-to-a-specific-message)
in the discussion thread, as message links will still work even if the topic is
renamed or resolved.
To encourage prompt attention and discussion for a bug report you have filed,
you can send a message in the Zulip development community with the key points
from your report. Be sure to [link to the GitHub
issue](https://zulip.com/development-community/#linking-to-github-issues-and-pull-requests).
See the following section for advice on where and how to start the conversation.
## Starting a conversation about a possible bug
If you are not sure whether the issue you encountered is a bug, or how to
reproduce it, we highly recommend reporting it in the [Zulip development
community](https://zulip.com/development-community/). It's the best place to
interactively discuss your problem.
Steps and best practices for starting a conversation:
1. [**Join** the Zulip development
community](https://zulip.com/development-community/) if you don't already
have an account.
2. Pick an **appropriate stream** to report your issue:
- [#issues](https://chat.zulip.org/#narrow/stream/9-issues) for issues with
the Zulip web app or server. A good default if you aren't sure which stream
to use.
- [#mobile](https://chat.zulip.org/#narrow/stream/48-mobile) for issues with
the mobile apps.
- [#desktop](https://chat.zulip.org/#narrow/stream/16-desktop) for issues
that are specific to the Zulip desktop app, and _do not_ occur in the web
app.
- [#zulip-terminal](https://chat.zulip.org/#narrow/stream/206-zulip-terminal)
for issues with the terminal app.
- [#production
help](https://chat.zulip.org/#narrow/stream/31-production-help) for issues
related to self-hosting Zulip. See the [troubleshooting
guide](../production/troubleshooting.md) for additional details.
3. **[Start a new topic](https://zulip.com/help/starting-a-new-topic)** for
discussing your issue, using a brief summary of the issue as the name of the topic.
If you aren't sure where to post or how to name your topic, don't worry!
Moderators can always rename the topic, or move the thread to another stream.
Once a possible bug is reported, members of the development community will jump
in to discuss whether the report constitutes a bug, how to reproduce it, and how
it can be resolved. The initial reporter can help by monitoring the discussion,
and replying to any follow-up questions. If the report is determined to be a
reproducible bug, a GitHub issue will be filed to keep track of it (see below).
## Managing bug reports
This section describes our bug management process. All community members are
encouraged to help make sure things run smoothly, whether or not they originally
reported the bug.
Whenever a bug is tracked in GitHub and also discussed in the development
community, be sure to cross-link between the issue and the conversation. [Link
to a specific
message](https://zulip.com/help/link-to-a-message-or-conversation#get-a-link-to-a-specific-message)
in the discussion thread, as message links will still work even if the topic is
renamed or resolved.
- If you encounter a definite bug with a clear reproducer and significant user
impact, it is best to both file a GitHub issue, and immediately start a
discussion in the development community. This helps us address important
issues as quickly as possible.
- For minor bugs (e.g., a visual glitch in a settings menu for very long stream
names), filing a GitHub issue is sufficient.
- If a potential bug discussed in the development community is confirmed to be
an actual, reproducible bug, anyone can help out by filing a GitHub issue to
track it:
- In some cases, especially if we're planning to fix the issue right away, the
issue description can be a quote from a message with a link to the
discussion -- no need to stress over making it perfect.
- [Use Zulipbot](../contributing/zulipbot-usage.md) to add the appropriate
labels, including “bug” and at least one area label; leave a comment if you
don't know what area labels to use.
- You can add the “help wanted” label (and claim the issue if you like) if
that is appropriate based on the discussion. Note that sometimes we won't
mark a reproducible bug as “help wanted”, e.g., if we want a core
contributor to take it on, if the fix will happen as part of a larger
project, etc.
- Don't forget to cross-link between the issue and the discussion.
- If a bug report in GitHub is not sufficiently clear, Zulip maintainers will
often encourage the reporter to discuss it interactively in the development
community.

16
docs/overview/release-lifecycle.md
View File

@ -176,15 +176,15 @@ The Zulip community feels strongly that all the little issues are, in
aggregate, just as important as the big things. Most resolved issues
do not have any of these priority labels.
We welcome participation from our user community in influencing the
Zulip roadmap. If a bug or missing feature is causing significant
pain for you, we'd love to hear from you, either in
We welcome participation from our user community in influencing the Zulip
roadmap. If a bug or missing feature is causing significant pain for you, we'd
love to hear from you, either in
[chat.zulip.org](https://zulip.com/development-community/) or on the relevant
GitHub issue. Please an include an explanation of your use case: such
details can be extremely helpful in designing appropriately general
solutions, and also helps us identify cases where an existing solution
can solve your problem. See [Reporting
issues](../contributing/contributing.md#reporting-issues) for more details.
GitHub issue. Please an include an explanation of your use case: such details
can be extremely helpful in designing appropriately general solutions, and also
helps us identify cases where an existing solution can solve your problem. See
our guides for [reporting bugs](../contributing/reporting-bugs.md) and [giving
feedback](../contributing/contributing.md#user-feedback) for more details.
## Client apps

2
help/support-zulip-project.md
View File

@ -67,7 +67,7 @@ Collective](https://opencollective.com/zulip).
## Help improve Zulip
* [**Report
issues**](https://zulip.readthedocs.io/en/stable/contributing/contributing.html#reporting-issues),
issues**](https://zulip.readthedocs.io/en/stable/contributing/contributing.html),
including both feature requests and bug reports. Many improvements to the
Zulip app start with a user's suggestion.