Skip to main content

Feed aggregator

Ubuntu MATE, Not Just a Whim

Linux Journal - 11 hours 58 min ago

I've stated for years how much I dislike Ubuntu's Unity interface. Yes, it's become more polished through the years, but it's just not an interface that thinks the same way I do. That's likely because I'm old and inflexible, but nevertheless, I've done everything I could to avoid using Unity, which usually means switching to Xubuntu. more>>

Categories: Linux News

Non-Linux FOSS: Screenshotting for Fun and Profit!

Linux Journal - Thu, 10/20/2016 - 07:20

I do a lot of my day-job work on a Windows computer. Part of this involves taking screenshots for training purposes. For years, I've used the built-in "Snipping Tool" that comes with Windows, but I've always hated it. more>>

Categories: Linux News

Nasdaq Selects Drupal 8

Linux Journal - Wed, 10/19/2016 - 15:30

Dries Buytaert announced today that Nasdaq Corporate Solutions has selected Drupal 8 and will work with Acquia to create its Investor Relations Website Platform. In the words of Angela Byron, a.k.a "Webchick", "This is a big freakin' deal." more>>

Categories: Linux News

Canonical Ltd.'s Ubuntu Core

Linux Journal - Wed, 10/19/2016 - 08:30

Canonical Ltd.'s "Snappy" Ubuntu Core, a stripped-down version of Ubuntu designed for autonomous machines, devices and other internet-connected digital things, has gained significant traction in the chipset/semiconductor market recently. more>>

Categories: Linux News

Build Your Own Raspberry Pi Camera

Linux Journal - Tue, 10/18/2016 - 04:30

During the past few years, my BirdCam setup has evolved significantly. As I mention in the UpFront section of this issue, I hope to get the stream transferred to a YouTube Live stream at some point, so I can watch the feathery show on my television. And although watching the birds is the end goal, I'm constantly on a mission to improve the quality and flexibility of my setup. more>>

Categories: Linux News

Netlist, Inc.'s HybriDIMM Storage Class Memory

Linux Journal - Mon, 10/17/2016 - 08:11

The metachallenge in today's data-saturated world is turning Big Data into actionable insight. A straight line to faster insights can be found in Netlist, Inc.'s new HybriDIMM Storage Class Memory (SCM), which the company describes as the industry's first standards-based, plug-and-play SCM solution. more>>

Categories: Linux News

Managing good bug reports

Anarcat - Fri, 10/14/2016 - 10:11

Bug reporting is an art form that is too often neglected in software projects. Bug reports allow contributors to participate without deep technical knowledge and at the same time provide a crucial space for developers to be made aware of issues with their software that they could not have foreseen or found themselves, for lack of resources, variety or imagination.

Prior art

Unfortunately, there are rarely good guidelines for submitting bug reports. Historically, people have pointed towards How to report bugs effectively or How to ask questions the smart way. While those guides can be useful for motivated people and may seem attractive references for project managers, they suffer from serious issues:

  • they are written by technical people, for non-technical people
  • as a result, they have a deeply condescending attitude such as calling people "stupid" or various animal names like "mongoose"
  • they are also very technical themselves: one starts with a copyright notice and a changelog, the other uses magic words like "Core dumps" and $Id$
  • they are too long: sgtatham's is about 3600 words long, esr's is even longer at about 11800 words. those texts will take about 20 to 60 minutes to read by an average reader, according to research

Individual projects have their own guides as well. Linux has the REPORTING_BUGS file that is a much shorter 1200 that can be read under 5 minutes, provided that you can understand the topic at hand. Interestingly, that guide refers to both esr's and sgtatham's guidelines, which means, in the degenerate case where the user hasn't had the "privilege" of reading esr's prose already, they will have an extra hour and a half of reading to do to have honestly followed the guidelines before reporting the bug.

I often find good documentation in the Tails project. Their bug reporting guidelines are easily accessible and quick to read, although they still might be too technical. It could be argued that you need to get technical at some point to get that information out, of course.

In the Monkeysign project, I have started a bug reporting guide that doesn't yet address all those issues. I am considering writing a new guide, but I figured I would look at other people's work and get feedback before writing my own standard.

What's the point?

Why have those documents been written? Are people really expected to read them before seeking help? It seems to me unlikely that someone would:

  1. be motivated enough to do something about a broken part of their computer
  2. figure out they can do something about it
  3. read a fifteen thousand words novel about how to report a bug...
  4. just to finally write a 20-line bug report that has no warranty of support attached to it

And if I would be a paying customer, I wouldn't want to be forced to waste my time reading that prose either: it's your job to help me fix your broken things, not the reverse. As someone doing consulting these days: I totally understand: it's not you, the user, it's us, the developers, that have a problem. We have been socialized through computers, and it makes us weird and obtuse, but that's no excuse, and we need to clean up our act.

Furthermore, it's surprising how often we get (and make!) bug reports that can be difficult to use. The Monkeysign project is very "technical" and I have expected that the bug reports I would get would be well written, with ways to reproduce and so on, but it happened that I received bug reports that were all over the place, didn't have any ways of reproducing or were simply incomplete. Those three bug reports were filed by people that I know to be very technically capable: one is a fellow Debian developer, the second had filed a good bug report 5 days before, and the third one is a contributor that sent good patches before.

In all three cases, they knew what they were doing. Those three people probably read the guidelines mentioned in the past. They may have even read the Monkeysign bug reporting guidelines as well. I can only explain those bug reports by the lack of time: people thought the issue was obvious, that it would get fixed rapidly because, obviously, something is broken.

We need a better way.

The takeaway

What are those guides trying to tell us?

  1. ask questions in the right place
  2. search for similar questions and issues before reporting the bug
  3. try to make the developers reproduce the issues
  4. failing that, try to describe the issue as well as you can
  5. write clearly, be specific and verbose yet concise

There are obviously contradictions in there, like sgtatham telling us to be verbose and esr tells us to, basically, not be verbose. There is definitely a tension in there, and there are many, many more details about how great bug reports can be if done properly.

I tend towards the side of terseness in our descriptions: people that will know how to be concise will be, people that don't will most likely not learn by reading a 12 000 words novel that, in itself, didn't manage to be parsimonious.

But I am willing to allow for verbosity in bug reports: I prefer too many details instead of missing a key bit of information.

Issue trackers

Step 1 is our job: we should send people in the right place, and give them the right tools. Monkeysign used to manage bugs with bugs-everywhere and this turned out to be a terrible idea: you had to understand git and bugs-everywhere to file any bug reports. As a result, there were exactly zero bug reports filed by non-developers during the whole time BE was used, although some bugs were filed in the Debian Bugtracker.

So have a good bug tracker. A mailing list or email address is not a good bug tracker: you lose track of old issues, and it's hard for newcomers to search the archives. It does have the advantage of having a unified interface for the support forum and bug tracking, however.

Redmine, Gitlab, Github and others are all decent-enough bug trackers. The key point is that the issue tracker should be publicly available, and users should be able to register easily to file new issues. You should also be able to mass-edit tickets and users should be able to discover the tracker's features easily. I am sorry to say that the Debian BTS somewhat falls short on those two features.

Step 2 is a shared responsibility: there should be an easy way to search for issues, and we should help the user looking for similar issues. Stackexchange sites do an excellent job at this, by automatically searching for similar questions while you write your question, suggesting similar ones in an attempt to weed out duplicates. Duplicates still happen, but they can then clearly be marked and linked with a distinct mechanism. Most bug trackers do not offer such high level functionality, but should, so I feel the fault lies more on "our" end than at the user's end.

Reproducing the environment

Step 3 and 4 are more or less the user's responsibility. We can detail in our documentation how to clearly share the environment where we reproduced the bug, for example, but in the end, the user decides if they want to share that information or not.

In Monkeysign, I have finally implemented joeyh's suggestion of shipping the test suite with the program. I can now tell people to run the test suite in their environment to see if this is a regression that is specific to their environment - so a known bug, in a way - or a novel bug for which I can look at writing a new unit test. I also include way more information about the environment in the --version output, an idea I brought forward in the borg project to ease debugging. That way, people can just send the output of monkeysign --test and monkeysign --version, and I have a very good overview of what is happening on their end. Of course, Monkeysign also supports the usual --verbose and --debug flag that users should enable when reproducing issues.

Another idea is to report bugs directly from the application. We have all seen Firefox or other software have automatic bug reporting tools, but somehow those seem unsatisfactory for a user: we have no feedback of where the report goes, if it's followed up on. It is useful for larger project to get statistical data, but not so useful for users in the short term.

Monkeysign tries to handle exceptions in the code in a graceful way, but could do better. We use a small library to handle exceptions, but that library has since then been improved to directly file bugs against the Github project. This assumes the user is logged into Github, but it is nice to pre-populate bug reports with the relevant information up front.

Issue templates

In the meantime, to make sure people provide enough information, I have now moved a lot of the bug reporting guidelines to a separate issue template. That issue template is available through the issue creation form now, although it is not enabled by default, a weird limitation of Gitlab. Issue templates are available in Gitlab and Github.

Issue templates somewhat force users in a straight jacket: there is already something to structure their bug report. Those could be distinct form elements that had to be filled in, but I like the flexibility of the template, and the possibility for users to just escape the formalism and just plead for help in their own way.

Issue guidelines

In the end, I opted for a short few paragraphs in the style of the Tails documentation, including a reference to sgtatham, as an optional future reference:

  • Before you report a new bug, review the existing issues in the online issue tracker and the Debian BTS for Monkeysign to make sure the bug has not already been reported elsewhere.

  • The first aim of a bug report is to tell the developers exactly how to reproduce the failure, so try to reproduce the issue yourself and describe how you did that.

  • If that is not possible, try to describe what went wrong in detail. Write down the error messages, especially if they have numbers.

  • Take the necessary time to write clearly and precisely. Say what you mean, and make sure it cannot be misinterpreted.

  • Include the output of monkeysign --test, monkeysign --version and monkeysign --debug in your bug reports. See the issue template for more details about what to include in bug reports.

If you wish to read more about issues regarding communication in bug reports, you can read How to Report Bugs Effectively, which takes around 20 to 30 minutes.

Unfortunately, short of rewriting sgtatham's guide, I do not feel there is much more we can do as a general guide. I find esr's guide to be too verbose and commanding, so sgtatham it will be for now.

The prose and literacy

In the end, there is a fundamental issue with reporting bugs: it assumes our users are literate and capable of writing amazing prose that we will enjoy reading as the last J.K. Rowling novel (if you're into that kind of thing). It's just an unreasonable expectation: some of your users don't even speak the same language as you, let alone read or write it. This makes for challenging collaboration, to say the least. This is where automated reporting makes sense: it doesn't require user's intervention, and the communication is mediated by machines without human intervention and their pesky culture.

But we should, as maintainers, "be liberal in what we accept and conservative in what we send". Be tolerant, and help your users in fixing their issues. It's what you are there for, after all.

And in the end, we all fail the same way. In an attempt to improve the situation on bug reporting guides, I seem to have myself written a 2000 short story that will have taken up a hopefully pleasant 10 minutes of your time at minimum. Hopefully I will have succeeded at being clear, specific, verbose and concise all at once and look forward to your feedback on how to improve our bug reporting culture.

Categories: External Blogs

Secure Desktops with Qubes: Compartmentalization

Linux Journal - Thu, 10/13/2016 - 06:00

This is the third article in my series about Qubes. In the first two articles, I gave an overview about what Qubes is and described how to install it. more>>

Categories: Linux News

Polishing the wegrep Wrapper Script

Linux Journal - Wed, 10/12/2016 - 05:00

When last I discussed shell scripts, I was presenting a shell script that offered an alternative to the -C context flag in GNU grep. more>>

Categories: Linux News

Android Candy: More Life Gamification

Linux Journal - Tue, 10/11/2016 - 09:15

You might remember a couple months ago my mention of Habitica, which is a gamification of your daily to-do list. One of my friends on Twitter mentioned an app he uses on Android called Wokamon, which ties in with your FitBit (or any of several other "step-counter" devices). more>>

Categories: Linux News

LinkedIn's {py}gradle

Linux Journal - Mon, 10/10/2016 - 08:00

To facilitate better building of Android apps, the technical team at LinkedIn has developed {py}gradle, a new powerful, flexible and reusable Python packaging system. Now available to the Open Source community, {py}gradle wraps Python code into the Gradle build automation tool so that developers can build Android apps more easily. more>>

Categories: Linux News

A New Mental Model for Computers and Networks

Linux Journal - Thu, 10/06/2016 - 12:30

One of the great works of geekdom is Neal Stephenson's In the Beginning Was the Command Line, an essay-length book that came out in 1999. As with Linux, the code was open. Still is. more>>

Categories: Linux News

Steven Ovadia's Learn Linux in a Month of Lunches (Manning Publications Co.)

Linux Journal - Wed, 10/05/2016 - 08:45

Yes, Steven Ovadia's new book for Linux "noobs" is titled Learn Linux in a Month of Lunches, but readers may need two-hour lunches and weekends to attain the ambitious goal implied in the title. more>>

Categories: Linux News

Senet IoT Foundry

Linux Journal - Tue, 10/04/2016 - 06:30

Startup companies and even large enterprises may not be able to harness the full range of skills required to deliver vertically complete IoT solutions to their customers. more>>

Categories: Linux News

The Peculiar Case of Email in the Cloud

Linux Journal - Mon, 10/03/2016 - 07:00

Most of the time when I start a project, or spin up a virtual server, it's done in my own basement "server farm". Not too many years ago, if I wanted those services to be public, I'd simply port-forward from my static IP into my personal machines. Or, perhaps I'd set up a name-based virtual host as a reverse proxy if I needed to expose a Web app. more>>

Categories: Linux News

Linux Journal October 2016

Linux Journal - Sat, 10/01/2016 - 10:00
Out with the New, and in with the Newer!

There was a show a few years back called, "Extreme Makeover: Home Edition". The premise of the show was to find families who needed their house more>>

Categories: Linux News

SUSECON 2016: Where Technology Reigns Supreme

Linux Journal - Fri, 09/30/2016 - 10:00
Article Sponsor:  SUSE

I love fall—the colors, the refreshing change in the air, the fall vegetable harvest. The best thing about this time of year, however, is SUSECON. It's happening this year November 7–11 in Washington, DC. more>>

Categories: Linux News

The Tiny Internet Project, Part I

Linux Journal - Thu, 09/29/2016 - 05:00

As LJ readers well know, Linux drives many of the technologies we use every day, from smart TVs to Web servers. Linux is everywhere—except most homes and classrooms. more>>

Categories: Linux News

Bitcoin on Amazon! Sort of...

Linux Journal - Wed, 09/28/2016 - 11:00

I was a Bitcoin fan before it was popular. That means I had thousands of Bitcoins. It also means I sold my thousands of Bitcoins for less than $1 each. Still, the technology fascinates me, and although cryptocurrencies have risen and fallen, I'm still a fan. more>>

Categories: Linux News

Free Today: September Issue of Linux Journal (Retail value: $5.99)

Linux Journal - Tue, 09/27/2016 - 10:27
For a limited time, the September issue of Linux Journal is free of charge, no strings attached, just click thru to start your download. (Retail price: $5.99 USD)


Categories: Linux News
Syndicate content