How to report an Issue for Adblock Plus

General rules

• Check for existing issue first
  To avoid duplicate issues, being worked on by different people with different approaches, please always first check for existing issues before creating a new one. Trac provides powerful query possibilities for that.

• Be precise
  It turned out that humans assume prerequisites of their thoughts to be obvious to everybody reading their issues. Apparently, that is true for rare cases only, so even if you are absolutely convinced, things are obvious, please always describe things in very great detail.

• Reuse existing language
  While work on a certain feature is underway, a specific language develops to talk about this feature in an efficient manner. Make sure to look out for such language and reuse it to avoid confusion and increase efficiency.

• Don't bury the description in the comments
  Don't put any part of the ticket into a comment. Instead change the description and comment your change. The comments are not part of the ticket and all additional parts of the ticket (priority, stage, etc....) don't and cannot apply to the comments.

• Attachments don't count
  Everything that needs to be done has to be described in the description. If a requirement is not in the description it will not be done and cannot be tested and cannot be verified. The attachments are only there to provide files that may be needed to fix the ticket. Attachments cannot easily be changed and have no version history, so if you attach multiple versions it's not clear which one is the correct version and if you replace the attachment with a newer version it is not possible to see earlier versions and detect errors or missing requirements in a new version of an attachment. So if using attachments, please always link the correct version of them in the description where required.
  

Types of Issues

Defects

A defect issue is the most common issue type and the most likely you want to create. It describes a malicious behaviour (a behaviour that differs from the behaviour that should occur) and should contain the following three major parts. Each part has to be described as accurately as humanly possible. This is because also seemingly obvious or unrelated details can be related to the behaviour and because the tester doesn't know which details matter and which not he has no other chance but to report everything. This includes a detailed description of the environment in which the defect occurs.

Required sections are:

• Which technical environment you are using
  This part describes details like the version of your operating system, your exact browser version, the used Adblock Plus version and the enabled Filter lists.
• How to reproduce the behaviour
  This is the most abso-positive-lutely important part of a defect issue. It describes how the defect can be triggered and allows the repeatedly observation of the behaviour, by providing step-by-step instructions, including which web browser, user account and test/live environment you have used. Without it the issue is virtually worthless and does produce nothing but unnecessary overhead.
• What behaviour you are observing
  This part describes which behaviour you are witnessing and allows to verify If the reproduced behaviour is the same, the tester observed.
• Which behaviour you are expecting
  This part describes what should occur and thus also defines what is to fix if the issue gets accepted.

Changes

Sometimes it's necessary to change an existing feature. If you want an existing feature to be changed or add a new one, you create a change issue. Often Always a change also affects other parts of the system. These must be considered in the issue itself you must think very hard and list every of such things in the issue. If the change leads to other huge changes it might be necessary to create new issues for that. You can link those issues together by the blocking/blocked by feature of the trac.

• Why you want the change
  Describe the existing problem by giving a short user story. Describe why the change should be made. This is to supply more background information about the change and helps to prioritize the change if needed.
• Which existing feature is to be changed
  To change something you have to know what to change and this part is exactly about that, describing what should be changed. Here you describe in every detail what should be changed, where you can find and what it does now. This is to verify that the feature on is about to change is the correct one. This includes that if you describe a text change you not only include the old and the new version of the text but also WHERE SOMETHING SHOULD BE CHANGED. Otherwise the text may be changed at a different location or for a location where it should not have been changed.
• What should occur after the change
  Here you describe in every detail what should occur after the change has been made. This is to define the change itself describing what has to be changed once the issue has been accepted.

Issue Fields

Summary

A one-sentence abstract of what and where the issue is about. Please ensure this to be both, unique enough to be understood as precisely as possible and short enough to be a summary. Please avoid summaries like "Adblock Plus is broken" without further details, as this could lead to a wrong priority perception when looking at the issue. If something only happens in a very specific case like at one website only, please mention it additionally directly in the summary to help us to get the right impression right from the scratch.

Description

This is where the detailed specification of your issue belong. The field is prefilled with sections required depending on the issue type you chose. Please keep the sections with their formatting and only replace the respective texts.

Type

Here you select whether you want to report a Defect or request a Change.

Platform

Here, you can set the Browser / System that your issue is related to.

Confidential

Please check this box, if you want to want to report a security issue that might harm users if revealed publicly before it is fixed. The issue is than hidden from the public until somebody unchecks the confidential setting once this is rolled out to the majority of users.

Verified working

Please leave this box unchecked until a moderator asks you to confirm a fixed issue actually works.

Additional issue Fields for Moderators

Priority

We have the following priorities for bugs and features:

P1 = This is time-critical, and needs to get tackled immediately.
P2 = This should get done as soon as possible.
P3 = We definitely want this, but it's not a priority.
P4 = We wouldn't mind having this, but it's unlikely to get done by the core team. ​Patches are welcome.
P5 = It's not clear if we really want to have this, needs to be discussed first.

Priorities are only assigned by ​module owners (or their peers).

Module

Here, you can select, which technical component your issue belongs to. Please find a description of available values at ​https://adblockplus.org/en/modules, leave "Unknown" if unsure.

Milestone

If it was already decided, in which upcoming release the issue shall be included, you might set the respective Milestone. If unsure, please leave empty.

Keywords

You might use comma-separated values to help finding issues of one common kind or to mark that this issue is a good one for contributors to start with, called ​goodfirstbug. Another common used keyword is externaldependency to show that an issue depends on things we cannot influence. Please always try to figure out, which similar existing keywords exist to to help finding issues again.

Cc

Dispatches an Email to the entered user/email address with changes to the issue, every time an issue was changed.

Blocked by / Blocking

To make the dependency of several issues from each other clear, you can enter issue IDs into those fields. "Blocked by" means the issue, you are editing cannot be resolved until the one entered in the field was fixed. "Blocking" means, the issue you enter into the field is blocked by the issue you are editing. After saving, there also appears a link in upper right corner being labelled "Depgraph" and showing the visual dependencies between this and other issues.

Owner

If it is clear, who will/shall work on this issue, you can enter his user name here. If unsure, please leave empty.

Review URL(s)

If some source code referring this issue was posted to be reviewed, add the respective URL(s) to the review(s) here.

Ready

To ensure issues to contain all required information, before somebody starts implementing them, this flag shall be set when all details are in the description, the issue is clear / reproducible and it was decided that we actually want do this. This flag is only set by the respective ​module owner (or their peers).

Tester

Select the tester who is assigned to this issue (to be set by Testers themselves).

Workflow

Right after creation, an issue has the state new. If you start working at an issue, please assign it to yourself. An issue may be set to fixed once your changes made it to the according repository. Please also check whether you could complete the issue with more details like a milestone.
In case you are a developer and have just fixed an issue, please make sure, testers can derive what to test from the issue. If your fix affects more than the function described in an change issue or needs more testing than the How to reproduce section, or your change is at a level way below functional, please provide a What to test section for testers giving them some hints.

For a full overview of our development process, see our visualizations:
Development process​
Release process​

Basic Symbol explanation (​Event driven process chain):

Orange hexagonal	Event that triggers the following function
Green rounded rectangle	Function that is executed triggered by the previous event
Grey rounded rectangle	Process interface that logically links to a subprocess
Yellow rounded rectangle	Role that executes the function connected to it
Grey rhombus	Connectors. Those can contain a “+” for “AND”, an O for “OR” or and “X” for XOR. + means, both incoming paths need to happen at once, O means one or both of the incoming paths may happen at the same time, X means only one of the incoming paths may happen at the same time.

Ticket resolutions

We have the following resolution choices when resolving an issue:

Resolution	To be set when
fixed	The bug was fixed or the change was implemented as described. If applicable, the corresponding commit should be linked in a comment and the issue should be assigned to the corresponding milestone.
incomplete	The issue lacks information required to work on it.
rejected	Fixing this issue isn't worth the effort, added complexity or potential side-effects.
duplicate	The same was already described in another issue, which should be linked in a comment.
worksforme	The described bug is not reproducible or the requested change is already implemented.
invalid	Either the assumptions in the issue are wrong or the issue is out of scope (e.g. filter list issues or browser bugs that cannot be worked around).

Whether to reopen or create a new issue

Please respect the logic, given in the flow chart below, when you report a bug, in order to decide whether to reopen the issue that has introduced the bug or to create a new issue instead. If you are not sure which issue to reopen, please create a new issue, rather than reopening the wrong one.

Note that as long as the implementation conforms to the ticket description, the issue is fixed. So if the description is erroneous you have to fix it before you reopen the issue. Leaving a comment isn't sufficient to change requirements, specifications or texts. All relevant details must be provided in the description and only the details included in the description are mandatory for the implementation.