How to write a great bug report

ladybug resting on a spiral plant shoot

As someone who frequently answers questions in the WordPress.com community support forums, the following suggestions from the JetPack blog on how to write a bug report are really excellent.

Often bug reports don’t include enough information. Meaning we have go back and ask for details so we can investigate. If you want to increase the odds we fix an issue, and fix it fast, help us out.

A great bug report includes the following:

  1. What were you trying to do?
  2. What did you click on or do last?
  3. What happened / what did you see?
  4. What browser are you using?
  5. What version of WordPress?  Not relevant for WordPress.com users, as we always have the most up-to-date version.
  6. What hosting provider? (And if you know, what version of PHP do they use?) Again, not relevant to WordPress.com users.

You don’t need to be verbose. A sentence for each is often just fine. And bug reports that show screenshots for #3 are incredibly useful, as we can see exactly what you saw.”

via How to write a great bug report — Jetpack.

Published by JenT

After 4 years hand-coding websites, 2 years setting up and running WordPress sites, I launched my first website on WordPress.com in 2006 and never looked back. Since then, I’ve helped other site owners safely navigate through the ins and outs of the ever-changing WordPress.com ecosystem. Find me at wpcommaven.com

5 thoughts on “How to write a great bug report

  1. This is good advice. I’m a software engineer myself, and recognise the need to provide as much information as possible so as to be able to identify the root of a problem. Far too many people don’t appreciate how essential this is!

    But the biggest issue of all is addressing one’s bug report/ feedback to those who can address it; and it seems to me that this is an issue that WordPress.com doesn’t acknowledge. They don’t (as far as I’m aware) offer any route for feedback — let alone bug reports!

    The ‘Happiness Engineers’ I’ve spoken with over the years, while very attentive and helpful in many respects, when presented with a flaw in the system either deny that it’s a problem (I’ve had that response on more than one occasion) or simply assure me that ‘they’ll escalate it’ (which sounds to me like a blatant platitude). It’s rare that the issues I report get fixed. The ongoing troubles in recent months with the ‘reblog’ facility is another. And don’t get me started on the ‘Gutenberg’ block editor!

    Your post here could benefit from a link to ‘the WordPress.com community support forums’ to which you refer; though I have my doubts whether any community forum can actually address software bugs, other than by suggesting possible workarounds. I think that GitHub is probably the best place to report bugs, though I’ve found that to be a really confusing site (for one thing, even once you clear the hurdle of understanding how GitHub works, it’s never clear whether a problem relates to ‘jetpack’, ‘calypso’ — which are utterly meaningless terms to the vast majority of WordPress users) — or, indeed, some other esoteric part of the open source WordPress platform.

    Here’s an example: I posted a bug report entitled ‘Inline CSS is lost in a List block when amending the content of the list‘ on GitHub in February of this year. It’s been six months, and that bug report has seen no activity whatsoever; not even an acknowledgement.

    1. Hello again! If you are connected to github, you might have seen the number of new bug reports or feature requests there. WordPress.com is a big place with millions of sites! For anything to get traction there, it usually means several people have reported the same issue. I don’t anticipate that most WordPress.com users know all those terms, they only need to know what’s not working for them and be able to provide the necessary information that might help get the issue resolved for them.

      For about the last 3 years especially, I recommend contacting Support directly either from the “contact support” link in your MySite Home dashboard or generally in your dashboard, through the Help bubble icon in the lower right corner of your screen. The reason is that will always bring you to the highest level of support available to you under your plan. If your site is on the free plan, it will route your question automatically to the community forums.

      *As far as getting some eyes on an issue, I have generated several github reports via support chats that have not been addressed for nearly a year, let alone resolved. Again, if it’s a “one-of” issue, unlikely it will be.

      *Edited to add

      1. Well, thanks for the time spent digging. But you just underscore my point: how is one supposed to know whether to post a bug report into these arcane terms, ‘jetpack’, ‘calypso’, or ‘gutenberg’? It’s all utterly incomprehensible.

Kvetch or kvell, it's all good, but be a mensch.

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.