開源日報 每天推薦一個 GitHub 優質開源項目和一篇精選英文科技或編程文章原文，堅持閱讀《開源日報》，保持每日學習的好習慣。
今日推薦開源項目：《有鬼(gui) youtube-dl-gui》
今日推薦英文原文：《How to write better bug reports》
今日推薦開源項目：《有鬼(gui) youtube-dl-gui》傳送門：GitHub鏈接
推薦理由：有想要下載 YTB 上視頻的朋友應該或多或少聽說過 youtube-dl 這個項目：一行命令就能幫你下載 YTB 視頻。而這個項目則是給它加上了一個圖形界面，對於不習慣命令行的人來說更友好些，在不記得命令的時候調整設置也更為簡單，適合作為工具推薦給身邊的朋友。
今日推薦英文原文：《How to write better bug reports》作者：Cristina M.
原文鏈接：https://medium.com/@cristina.mtys/how-to-write-better-bug-reports-b03eeb4726ed
推薦理由：在一個人編程的時候可能不需要 Bug 報告，但是這種寫報告分析 Bug 的思想也能幫你理清解決它的思路

How to write better bug reports

Probably you encountered bug reports that are as long as this article or so short that you cannot even reproduce it. No matter if you are a developer, a quality assurance or a manager, a good written bug report can save you ton of time.

Photo by Glenn Carstens-Peters on Unsplash

We all need to understand that a bug report has to be as short as possible, and written with simple and concise words. That is all, nobody needs an essay.

I am a QA and sometimes I get reports from the clients or developers that are not explicit at all:
  • Bug description: Setting is saved only after reset.
What setting? Should I reset the application, the device? Well..please, tell me, how exactly can I reproduce that?

OR the classic
  • Bug description: Application does no work.
What did you do that it stopped working? Works perfectly fine for me..

OR

Sometimes I get a very very long report. No spaces or punctuation, only text. Long phrases that make me forget what was it all about? Am I reading a novel? Oh wait, it is a bug which needs to be reproduced and converted to a easy to understand format.

Why should I waste time and try to add an easy to read format?

Because if I assign the issue to a developer, he』ll be bored and stop reading after the second row. As a result I』ll get the bug back in QA saying that it is solved.
  • What ? So fast?
Yeah, probably he』ll say that the bug cannot be reproduced (of course, he didn』t tried, and I』m not even blaming him for that), or he』ll fix another issue found when trying to reproduce the critical one that we got from clients (of course, he』ll not let me know that he fixed a totally different issue, so he can get rid of the complicated one).

The only scope of a bug report is to be easy to understand, so the developer is able to reproduce it.

The report should contain the following information:
  • Title: it should be short and explicit, most of the time is a summary of Actual Result

  • Steps to reproduce: a list with numbers or bullet points with the exact actions needed to be executed in order to catch the bug

  • Actual result: describe exactly what is happening after doing the steps

  • Expected result: explain what it should happen after doing the steps

  • Severity: can be Low, Medium, Major or Critical and refers to the impact of the bug

  • Notes: I』ll add here any information that I consider useful for the reproduction of the bug. Device, operating system, browser name and version are some of the details that I consider important. For desktop applications the build number is also added. This part could be specific to each project.

  • Attachment: video or photo

Except UI bugs, where a photo is explanatory enough, I personally like to add short videos with the steps, it saves a lot of time and developers have no excuse to send the bug back with the reason that they cannot reproduce it. I create the videos without sound and no longer than 1 min or 1 min and half, as that is long enough to execute the reproduction steps, and short enough to not loose the attention of the viewer.

Some people add gifs. I do not like that, especially for longer scenarios, because you cannot pause it. It』s going in the loop for a while until I can understand what is there.

Also I like to add the error that the console throws, or at least keep that open while creating the screen record so it will be easier to debug and understand why that scenario fails.

Now lets see a practical example

First example: DON』T


Photo by Kai Pilger on Unsplash

Title: Application not working as it should

Steps: 1. Open the online shop 2. Add a product to the favorite list Actual: Product is not added

Expected: Application should work correctly

Severity: Critical

Notes: Tested on my local computer

First, the title is very general, it should be more specific and refer exactly to the bug that is described.

Second, the steps are not clear enough, the bug may be related to specific buttons or products and the bug does not state what buttons to click.

Third, actual result could be more detailed. Does it throw any error, is the user redirected or is the button even clicked?

Fourth, a critical severity refers to a defect that shuts down the system. Lets not create panic, you should add Critical severity only if that application is down or something like that.

Fourth, add exactly what should happen after doing those steps. Correctly can mean different things to every person. You should have a requirement from the client that states what correctly means for that particular application, so please use that as an expected result. The bug may be fixed in a wrong way if we use such a general statement in the expected results.

Last, be more specific about your computer: OS and browser used.

Lets see the correct example now:

Example number 2: DO


Photo by Carlos Alberto Gómez Iñiguez on Unsplash

Title: Error is displayed when adding a product to favorites list

Steps: 1. Open the online shop (add the name/link to the shop if the team is working on multiple projects) 2. Search for iPhone XR 3. Select the product 4. Press on Add to favorites button Actual: 『Error』 message is displayed on the screen and the product was not added to the favorites list

Expected: 『Successfully added to your list』 message is displayed and user can find the product in the favorite list

Severity: Medium

Notes: Tested on Windows 10, Chrome 74.0.3729.169
下載開源日報APP：https://openingsource.org/2579/
加入我們：https://openingsource.org/about/join/
關注我們：https://openingsource.org/about/love/