Two bug hunt days are held monthly, on the third Thursday and Friday of the month.
During those days, the Zend team will be in #zftalk.dev on Freenode for the entire work day. We will be triaging bugs ourselves, but, more importantly, we will be there to help facilitate you, our contributors and users, in resolving issue reports.
As an incentive, each month, we will ship a Zend Framework t-shirt to the individual that assists in the most issue resolutions during the bug hunt days, whether via patches or direct commits. Contributors are tracked by who the tickets were "assigned" to, so be sure to assign all tickets that you resolve to yourself in order to be counted. Quarterly, we will evaluate overall contributions, including documentation, bug fixes, and newly contributed components, and award a developer with their choice of a Zend Studio license or Zend Framework Certification voucher. (Caveat: one t-shirt per person per year, and one license/voucher per person per year, folks!)
For those interested in participating in the bug hunt days, the rules are simple: have a signed CLA on file, and resolve issues in the tracker.
If you have not yet signed a CLA and want to participate, you can get a copy of the form here:
Sign it and return it (you can email it, fax it, or send it via post); if you send it via post, you'll need to wait for confirmation that we've received it before we can accept code contributions from you.
Now, when it comes to the issue tracker, you'll need to determine if the issue:
- is simply the reporter misunderstanding or misusing code OR
- is a request for a new feature OR
- is a reproducible issue
In the first case, comment on it and indicate the correct usage, and ask the component maintainer or somebody from Zend to review your response and mark the issue as resolved. In the second case, please try and focus on issue reports instead of feature requests during the bug hunt days.
That brings us to the final case, reproducible issue reports. With these, you'll need to do the following:
- Capture the reproduce case as a unit test
- Resolve the issue in such a way as to maintain backwards compatibility with existing usage. (In other words, don't change the signature of a method unless the signature is what is actually broken.)
From there, you then have two options:
- If you already have commit access, commit the test and fix to the repository, and either resolve the issue or ask somebody from Zend to review and resolve. Don't forget to merge your changes to the 1.9 release branch!
- If you do not have commit rights, create a patch with the unit test and fix, and attach the patch to the issue. Ask the maintainer or somebody from Zend to review and apply the patch. Usually posting in #zftalk.dev something to the effect of "Hello, patch attached to ZF-12345 is ready for review. Is anyone available?" will get the attention of someone available to do a commit for you.
If you need help creating the unit test or patch file, hop onto the #zftalk.dev IRC channel and ask for help.
How should you choose issues to work on? Answer the following questions, and you should be able to hop right in:
- What components do you have expertise in?
- What components are you interested in learning more about?
- What issues have a high number of voters or watchers?
Bug hunting should be fun, so pick components and issues you're interested in. Ask questions on IRC if you don't understand how something works.
In general, the following steps will help you be a more effective bug hunter, and also assure that your patches will be accepted and applied in a timely manner.
Not feeling confident with unit testing? Don't have a lot of time to help? Consider helping with documentation issues! There are many documentation issues posted that are often as simple as correcting typos or fixing examples. For a list, visit the docs filter in the issue tracker.
When updating documentation, please create patches following the rules outlined below under the heading "Create a patch."
Good reporters will provide all the information necessary to reproduce the issue they're reporting. This will include the minimum code necessary that reproduces the problem, what results they were expecting, and what actual results they observe.
Your job is to:
- Determine if you have all the above information, or if the information is implied in the report. If not, post a comment, and ask the reporter for the information you need. If the reporter does not provide the information in a timely manner (give it a week or two), we can close the issue as "Incomplete" or "Can not reproduce."
- Capture the reproduce case as a unit test. As an example, if somebody posted the following:
You would then capture it in a unit test as follows:
This test method would be placed in the appropriate test class. There are several things to note about this example. First, the docblock contains an "@group" annotation referencing the issue; this is so others looking through the tests know what issue this method is related to, and also allows us to run unit tests specific to the issue (via the syntax 'phpunit --group ZF-XXXX'). Second, the method name is descriptive of the behavior we're testing; it's self-documenting. Third, note the usage of assertions: learn the variety of assertions available in PHPUnit, and choose the assertions pertinent to the behavior you're testing.
- Run the unit tests to verify the failure. If the tests still pass, revisit your reproduce case to see if it accurately represents the report. If so, we can likely close the issue as "Can not reproduce." Regardless, you should still create a patch with the test, to show that the behavior is correct.
Once you have a reproduce case and it's captured in a test, you can finally start fixing the code. Keep in mind the following guidelines:
- Run your tests. After you change the code, run your tests to see if they now pass. Also, run the AllTests suite for the component, to ensure you didn't introduce breakage elsewhere.
- Don't change method signatures. If you change a method signature, you're potentially creating a backwards compatibility break. The only changes that are allowed:
- Additional, optional parameters
- That's it. Really.
- Don't change return values. Consumers of the code operate on the return values, so changes to those will, again, introduce backwards compatibility breaks.
- New methods are allowed, but try to minimize the number of them and how the rest of the class interacts with it. In particular, be cognizant of any interfaces the class is implementing, or having consuming classes utilize the new method.
- In extreme cases where a "rename" of a function is required or you feel it is critical to change the method signature to address an issue, then mark the existing method in the docblock as "@deprecated since <version> <explain reason>", create the new method, and modify the existing method to proxy to the new method so that its behavior remains unchanged. Write a unit test to confirm that the behavior. At some point in the future (i.e. a major version number change from 1 to 2, where BC breaks are acceptable), and only at this time, the deprecated method may be removed from the codebase.
Creating a patch is fairly easy, once you know what to do.
We recommend always creating patches from the root of your ZF install (i.e., the directory containing "library," "tests," and "documentation"); this makes it trivially easy to apply the patches, and also helps ensure that you're creating patches that include both tests and code.
Here are some typical methods for creating patches from the CLI:
- Using svn: svn diff > ../<issueid>.patch
- Using git: git diff -p --raw > ../<issueid>.patch
- Using an untouched source and modified source directory: diff -ur original/ changed/ > <issueid>.patch
Attach the patch to the issue, and assign it to yourself. Notify the component lead or someone with commit access in #zftalk.dev that the patch is ready for review. Alternately, if you have commit rights, you can skip creating the patch, and commit it directly. If the functionality affects the current minor release, be sure to merge your commit to the appropriate release branch. Once the commit has been made, update the ticket to reflect the fix version (i.e. "Next Mini Release") and mark the ticket as resolved (fixed).
Keep at it! The more issues we close, the better the framework will be!