This post is a translation from Portuguese, originally written to the equinociOS magazine.
It’s very easy to find developers that have found some kind of bug in third party code. Whether it’s in an external lib, or in Apple’s SDK. Our code, beautiful and sparkly, with undesired behavior caused by people that aren’t even in our company. At the same time, it isn’t hard finding devs that have reported some of these bugs to those responsible by the code, or that have contributed in any way to its resolution. But, it’s not so easy to find developers that have reported some kind of inconsistency to Apple.
The lack of material on bugreport, may it be motivational or guidelines, emphasize this fact. Frequent are the reports without relevant information, with confidential data, or identical copies of previous reports without addition of any new data.
In the sphere of Apple platforms development, doesn’t matter how individualistic you are. Even if you don’t use any third party libraries, we’re all under Apple’s SDK dome. May your code be as bulletproof to outside developers as it is, we’re all subject to the hits and misses of Apple’s developers.
Shed a light on the problem
The main reason to report a bug isn’t obvious. Tools of issue tracking were created to report incidents, i.e. to draw attention to an unexpected behavior.
Secondly, the resolution of the bug motivates the report. If there’s a workaround, or any way to avoid the problem in hand, fixing the bug might not have priority.
Nonetheless, we can never forget those who maintain these libraries. Reporting an issue demonstrates support to the code we use and to the people that build it, therefore, do not apologize for reporting a bug: appreciate the creation of that library.
Bugreport is money
Big companies have so much need of help that they turned Bug Bounty programs commonplace. The demand for reports on exploits and vulnerabilities is so big that Facebook, Github, Google, Microsoft and many other companies recognize and reward those who discover and resolve bugs before these inconsistencies become public.
In 2016 the US Department of Defense announced their Bug Bounty program called Hack the Pentagon in which security specialists where invited to attack the Pentagon’s public pages in search of security breaches. More than US$71,000 were paid in rewards.
Also in 2016, Apple announced their Bug Bounty program. Some say of rewards of up to US$200,000, but joining the program is only possible through invitations.
4 steps for a good report
Several platforms offer report templates. Github itself provides the CONTRIBUTING guidelines file so that each repository documents how to report and contribute to code development. However, with so many possibilities and without a standard, it’s not always easy to be concise when redacting a report.
1. Be clear about the inconsistency
In the introduction, be clear about the obtained behavior. What was expected? What is actually happening?
2. Define the steps to reproduce the bug
Include the steps for reproduction and inform if the behavior is intermittent. It’s okay if you can’t reproduce the bug every single time, but say so and be sure that the provided steps lead to some inconsistency.
3. Include snippets of code
If it’s a report to Apple, always attach a project or playground containing the bug reproduction in your radar. If it’s an issue on Github, you may include snippets of code or even links to repositories containing an example project or playground.
4. Suggest a fix or workaround
If you know what’s causing the bug or where it’s triggered, suggestions of fixes are more than welcome. Or, even better, fix the inconsistency and open a pull request with the solution.
Bugreports to Github
I believe Github require extra special caring when reporting incidents, after all, in open-source repositories, people contribute out of good-will and, although they may be responsible for the code, it’s nobody’s job to fix the errors and inconsistencies affecting you.
It is important not to be afraid of saying something wrong. The iOS community, specially, is super receptive and tolerant. No one will point fingers, or make fun if you say something incorrect. At most, you will be corrected politely.
The common language of the internet is the English Language, but not everyone is fluent and even less have it as native tongue. Don’t be embarrassed nor afraid of speaking English. It is common to find people from all over the world making grammar mistakes and nobody is corrected, ignored, or bullied because they didn’t spoke perfect English. We make mistakes even when writing in our own language, what to say of an idiom that isn’t our own (this post might even have a few). Remember that practice leads to perfection.
You also need to have in mind that the projects and libraries in Github are communitarian, consequently, as in every democracy, per se, it is common that corrections and increment proposals are thoroughly debated before coming to an agreement on how to proceed. Therefore, be coherent, have patience, and know how to argument listening to the opposing side. This might be a fantastic opportunity for you to deepen your knowledge on that tool and also receive comments on your code from amazing developers that create and maintain the most used libraries in the world. So listen and learn!
Bugreports to Apple
Apple has its portal where issues and feature requests may be reported. With an interface of doubtful taste (doesn’t seem like Jony Ive).
For those of whom that don’t like the portal, there’s also QuickRadar that provides a much cleaner interface and doesn’t require you to login every time you report an issue, besides also offering a simple template in a single text field.
Bugs reported to Apple are private for security reasons. Although the bulk of bugs may be behavioral, there are vulnerabilities and security breaches that might be exploited to leverage users and that can’t become public to avoid exposure. Because of this, appeared OpenRadar, that tries to mirror Apple’s portal, where developers replicate their reports to make them public. One of the advantages of QuickRadar is sending your issues automatically to OpenRadar as well, relieving the need of filling everything twice.
OpenRadar also provides the possibility of commenting on issue pages, which adds a much richer dynamic on the interaction with the community. In 2016 I reported a bug on UICollectionView that Apple engineers discarded as being the designed behavior. I disagreed of the decision because it isn’t how it worked before but since a documented bug is a feature I asked that it would be added to the documentation - request that was ignored - and, on rdar://28323532, we can see that user nicolas.millasseau also disagrees with the engineers decision.
Report duplicates
Don’t be shy nor demotivated if your bugs are being flagged as duplicates. It is unlikely to be the first to report an incident, which makes the occurrence of duplicates even more common, but it doesn’t diminish its relevance, since the greater the amount of people being affected by a problem, more the issue’s priority tends to rise. Furthermore, duplicates present different approaches to an inconsistency.
Consequently, when reporting a duplicate, you are providing more information which might help in the resolution of an incident. It may be that you are being able to reproduce the bug in a different manner, or that you might know a solution or workaround to what happened, or even that your crashlog has complementary data to previous reports.
On Github, there’s somewhat of a controversy regarding 👍. I believe it to be important to add +1 to issues as a way of flagging a duplicate, because it describes that there are more people being affected by that inconsistency, however there are those who believe that it doesn’t add nothing to the issue. In that regard, on session 213 of the WWDC, Apple’s engineers request that, when reporting a radar, one shouldn’t simply copy and paste an existing one because it does not add information nor increase the issue’s priority.
If any of your radars is flagged as a duplicate, you will be informed the id of the original issue, which may be searched on OpenRadar, where you can read comments to know if there’s a workaround, what is its current status (if it’s updated), and what the community is talking about it in general.
Deal with it 🕶
“Don’t introduce problems; present solutions” - myself
Take this mantra in your life: “complain less”. If you have the power to change something, do not complain: change it! If you don’t have the power required to change, what point there is in complaining? When dealing with a situation, whether at work, at home, or on the street, do not introduce a problem: present a solution. This doesn’t mean you should report less bugs, quite on the contrary! Reporting an issue is the first step to solving it.
If you report a bug, whenever possible, present a fix or, at least, a workaround for it. If it’s on Github, submit a pull-request. Be pro-active and resolve your own issues instead of waiting on others to fix them for you.
There’s no point on crying without acting. Shed a light on the problem. Be part of the solution. Improve the tools you use on your daily basis. Diminish your pain. Optimize your time. Help the community grow. Meanwhile, you’ll grow with it.