6 ms·

Why I keep a personal log of bugs

47 points by josem 6y ago

kowlo 6y ago
It's been over a year since you made this post - did it help? Did Buffer adopt it as good practice? The post is titled "Why I keep a personal log of bugs" but I didn't learn much about why you keep a personal log of bugs.
simonw 6y ago
I've been using GitHub issues for this for a couple of years, and I really like it. Any time I run into a bug, no matter how minor, I open an issue for it. I then use comments on that issue to track every step I use to fix it - adding screenshots, pasting in blocks of command-line output, linking to debugging tools I use etc. I usually end up with an issue thread with a dozen or so comments, all by me. I often refer back to old issue threads to remind myself how I debugged something. Here's an example from yesterday: https://github.com/simonw/datasette/issues/1124 https://github.com/simonw/datasette/issues/1124
- vincentmarle 6y ago
  Very interesting, thanks for sharing - but also looks like a lot of work. What's the overhead in doing this additional work?
  - dkdk8283 6y ago
    It’s easier than trying to remember it all. I have a habit of doing this at work, and it benefits not only me but the next person who needs information. It helps justify promotions and raises too. When you can do this openly it helps build a public body of work that can earn you better jobs.
    - orastor 6y ago
      People like you are the reason for impostor syndromes
  - simonw 6y ago
    The overhead is really slim. I'm basically using issue comments as personal notes - the time consuming part is figuring out what to do, while turning that into a sentence of text and maybe a link or pasted example is a fraction of that effort. And the productivity boost I get from having useful notes is enormous. It's particularly valuable for multi-tasking: I can have a lot more projects on the go at once if I don't have to remember details of what I was working on or where I had got to for each one.
- rualca 6y ago
  > Any time I run into a bug, no matter how minor, I open an issue for it. I then use comments on that issue to track every step I use to fix it - adding screenshots, pasting in blocks of command-line output, linking to debugging tools I use etc. Not to be snarky or anything, but isnt't that how they were always intended to be used? At least in each and every single job I had, that's how tickets were always used.
  - simonw 6y ago
    Until recently I used them like that for collaborative projects with other people, but not for personal projects where I was the only participant.
    - rualca 6y ago
      I still don't get it. Keeping a public worklog is intended to help other people, not yourself. That's why you're keeping your logs public, not in your personal engineering notebook. You post stuff in the ticket to make that stuff public, and keep it public, and allow others to see and query it.
      - simonw 6y ago
        My personal engineering notebook IS my public issues now, for all of my open source projects (which is almost all of my projects).
sevencolors 6y ago
This is a great example of why personal logs/diaries/journals/notes (whatever you call it) are a useful tool. It allows you to have a historical record of what happened. The simple act of documenting something in a structured manner seems to help commit the fragment to long-term memory. Personally I'm using the bullet journal method. * Has a good base structure and allows your own customization * Physically writing something down feels like it sticks in my memory later. For me notes I store digitally tend to vanish from my brain. YMMV * I look cool with my leather notebook ;)
MauranKilom 6y ago
I've maintained such a log in a text file, but only for bugs where I actually facepalmed when I realized how I screwed up (and how much time I just spent debugging a really elementary problem). Thankfully it happens only a few times per year. Most of them are along the lines of not fully implementing (either in typing or in touching all nearby places) some minor change while I'm iterating on an algorithm. Here are a few (condensed and simplified) examples: "Unfinished business..." if (target.size() == 2) sliceValue = valuePerSlice[z] = sliceValue; (Our linter would of course catch this, but it runs automatically only on the CI.) --- "Variables change when they are assigned!" ret[0] = scale * normalVector[0]; ret[1] = scale * a; if (normalVector[1] < 0) { ret[0] = std::sqrt(2) - ret[1]; ret[1] = std::sqrt(2) - ret[0]; } (The reassignments inside the if previously used their own instead of the other index.) --- "Back when I didn't trust my refactoring tools" Original code: for (unsigned tr0 = 0; tr0 < triangles0.size(); ++tr0) { if (std::find(triangles1.begin(), triangles1.end(), triangles0[tr0]) != triangles1.end()) return triangles0[tr0]; } After my change: for (unsigned tr0 : triangles0) { if (std::find(triangles1.begin(), triangles1.end(), triangles0[tr0]) != triangles1.end()) return tr0; } (Don't refactor absent-mindedly!)
- eyelidlessness 6y ago
  > Our linter would of course catch this, but it runs automatically only on the CI This is why, unless it’s a significantly degraded experience, I run a local watch version of what I expect to run in CI during dev. And if it is a significantly degraded experience I stop what I’m doing to either fix that (if possible) or refine it to at least approximate the CI validation automatically.
moron4hire 6y ago
Along this line of thinking (constant improvement), I made a big effort to excise the word "bug" in favor of "defect" in my speaking patterns. The word "bugs" implies that the issue got in from the outside, crawled into the works. It might even connote that it's a natural thing, that it has some sort of agency of its own. A "bug" is nobody's fault, unless someone's job was to keep the window closed and they failed at that job. The word "defect" is much more accurate. They were always there. That didn't just show up one day. They are an inherent artifact of a failure somewhere in the specification/design/development/testing process. Now, we might be generous and forgiving folk and not visit punishment on the person(s) who failed in that process, but that doesn't change the fact that it was a person who made the defect.
flippinburgers 6y ago
One more bug: not using vimwiki.
chaostheory 6y ago
This is pretty much what you need to do if you work for a US telecom. It felt like I spent more time with documentation than programming.
mjgs 6y ago
I could see this being a useful habit but if it’s just using vim and text files, it would be very tedious. I think you would need a tool to easily add, view and search to make it practical. Generally I like the idea of creating personal logs. I have a linkblog where I log all the important links I read: https://links.markjgsmith.com https://links.markjgsmith.com
- bombastry 6y ago
  In Emacs, an org-capture template[1] can be used to quickly and easily append new items to logs. It can prompt the user to enter text in multiple locations, eliminating the need to navigate around boilerplate to write entries. It can also prompt for tags to help make organization and searching easier. Additionally, it has the benefit of being callable anytime and anywhere within Emacs. I've only recently gotten around to using them, but they're really nice for quickly logging things that I was too lazy to do otherwise (e.g. recipes I have tried). [1]https://orgmode.org/manual/Capture-templates.html https://orgmode.org/manual/Capture-templates.html
  - mjgs 6y ago
    That sounds kind of cool, though I’m not very familiar with emacs so it looks a bit strange to me. Does it essentially create the emacs equivalent of an html form, that you fill out and it then adds what you added to preconfigured text files, with the path to the file you were looking at when you triggered the template?
    - bombastry 6y ago
      Org-Capture creates a temporary buffer, inserts its template string, processes the special escape sequences (called "%-escapes")[1], and then lets the user edit the buffer before adding it as an entry. Where the entry goes is specified by the code that sets up the template. The power here comes from the %-escapes, which range from asking the user for a prompt and pasting it in that location ("%^{PROMPT}") to arbitrary code execution ("%(EXP)") that can include text input from the user from other %-escapes. There are escapes to insert the file name ("%f") and the full file path ("%F") of the file that was visited when the template was triggered. I think it's a lot easier to evaluate this kind of thing in action rather than in screenshots, so I've added an example screen recording[2] with a keylogger to show what a capture using a fairly simple template looks like. This Imgur album has both the screen recording as well as what the resulting entry looks like after it is saved. [1]https://orgmode.org/manual/Template-expansion.html https://orgmode.org/manual/Template-expansion.html [2]https://imgur.com/a/l8jwbnN https://imgur.com/a/l8jwbnN
spc476 6y ago
Starting back around 2009, I started marking bug fixes in git with the first line containing "Bug fix---description". For example (from my gopher server [1]): a12c3fd Bug fix---sample forgot POST method. 0b1bce2 Bug fix---grab guid when only given numeric uid. 31408da Bug tracking---crash because filename is nil? d993265 Bug fix---Clean the display text to prevent broken index files. 47e98e8 Bug fix---line comments were broken in .port70 files. I do the same at work. I got the idea from Donald Knuth, who wrote a paper about classifying each error in TeX [2]. I didn't go as far as he did, but I still have his list handy: * Algorithm * Blunder * Cleanup * Data * Efficiency * Forgotten * Generalization * Interaction * Language * Mismatch * Portability * Quality * Robustness * Surprise * Typo [1] https://github.com/spc476/port70 https://github.com/spc476/port70 [2] "The Errors of TeX" <https://yurichev.com/mirrors/knuth1989.pdf https://yurichev.com/mirrors/knuth1989.pdf>
- l0b0 6y ago
  Very similar to Conventional Commits[1], with this structure: <type>[optional scope]: <description> [optional body] [optional footer(s)] It's supported by pre-commit[2], which is an excellent way to set up commit rules and linting. [1] https://www.conventionalcommits.org/en/v1.0.0/ https://www.conventionalcommits.org/en/v1.0.0/ [2] https://pre-commit.com/ https://pre-commit.com/
  - auslegung 6y ago
    At first, conventional commits sounds neat because they say you can > Automatically generating CHANGELOGs. > Automatically determining a semantic version bump (based on the types of commits landed). And I would really like those features. However it seems like this assumes 1 commit per feature, which I think is not the conventional wisdom. Am I missing something? For example, the feature is to add a new page to the site where the user can view all their posts. That should break down into several commits: add new route, add parser on frontend, add html structure, etc. But each of those commits would have to start with `feat: add route to fetch user's posts` and so on. Wouldn't that result in a unhelpfully verbose changelog, when the changelog should really feature one line: "Allow users to view all of their posts in one place"
itsmemattchung 6y ago
I 100% agree with the blog post, that everyone should collect a journal of bugs. However, looking at the author's example, I can't help but think that the "fix" for the bug is really just a good intention. More specifically, they were bitten by a bug where an environment variable wasn't set in production. Checking that the environment variable, in the future, is set is a nice next step however, I would say, another take away would be to encode that intention in the code directly: throw an error, emit a metric, log an error (that hopefully gets monitored).

47 points by josem 6y ago

It's been over a year since you made this post - did it help? Did Buffer adopt it as good practice? The post is titled "Why I keep a personal log of bugs" but I didn't learn much about why you keep a personal log of bugs.

simonw 6y ago

I've been using GitHub issues for this for a couple of years, and I really like it. Any time I run into a bug, no matter how minor, I open an issue for it. I then use comments on that issue to track every step I use to fix it - adding screenshots, pasting in blocks of command-line output, linking to debugging tools I use etc. I usually end up with an issue thread with a dozen or so comments, all by me. I often refer back to old issue threads to remind myself how I debugged something. Here's an example from yesterday: https://github.com/simonw/datasette/issues/1124 https://github.com/simonw/datasette/issues/1124

vincentmarle 6y ago
Very interesting, thanks for sharing - but also looks like a lot of work. What's the overhead in doing this additional work?
- dkdk8283 6y ago
  It’s easier than trying to remember it all. I have a habit of doing this at work, and it benefits not only me but the next person who needs information. It helps justify promotions and raises too. When you can do this openly it helps build a public body of work that can earn you better jobs.
  - orastor 6y ago
    People like you are the reason for impostor syndromes
- simonw 6y ago
  The overhead is really slim. I'm basically using issue comments as personal notes - the time consuming part is figuring out what to do, while turning that into a sentence of text and maybe a link or pasted example is a fraction of that effort. And the productivity boost I get from having useful notes is enormous. It's particularly valuable for multi-tasking: I can have a lot more projects on the go at once if I don't have to remember details of what I was working on or where I had got to for each one.
rualca 6y ago
> Any time I run into a bug, no matter how minor, I open an issue for it. I then use comments on that issue to track every step I use to fix it - adding screenshots, pasting in blocks of command-line output, linking to debugging tools I use etc. Not to be snarky or anything, but isnt't that how they were always intended to be used? At least in each and every single job I had, that's how tickets were always used.
- simonw 6y ago
  Until recently I used them like that for collaborative projects with other people, but not for personal projects where I was the only participant.
  - rualca 6y ago
    I still don't get it. Keeping a public worklog is intended to help other people, not yourself. That's why you're keeping your logs public, not in your personal engineering notebook. You post stuff in the ticket to make that stuff public, and keep it public, and allow others to see and query it.
    - simonw 6y ago
      My personal engineering notebook IS my public issues now, for all of my open source projects (which is almost all of my projects).

sevencolors 6y ago

This is a great example of why personal logs/diaries/journals/notes (whatever you call it) are a useful tool. It allows you to have a historical record of what happened. The simple act of documenting something in a structured manner seems to help commit the fragment to long-term memory. Personally I'm using the bullet journal method. * Has a good base structure and allows your own customization * Physically writing something down feels like it sticks in my memory later. For me notes I store digitally tend to vanish from my brain. YMMV * I look cool with my leather notebook ;)

MauranKilom 6y ago

I've maintained such a log in a text file, but only for bugs where I actually facepalmed when I realized how I screwed up (and how much time I just spent debugging a really elementary problem). Thankfully it happens only a few times per year. Most of them are along the lines of not fully implementing (either in typing or in touching all nearby places) some minor change while I'm iterating on an algorithm. Here are a few (condensed and simplified) examples: "Unfinished business..." if (target.size() == 2) sliceValue = valuePerSlice[z] = sliceValue; (Our linter would of course catch this, but it runs automatically only on the CI.) --- "Variables change when they are assigned!" ret[0] = scale * normalVector[0]; ret[1] = scale * a; if (normalVector[1] < 0) { ret[0] = std::sqrt(2) - ret[1]; ret[1] = std::sqrt(2) - ret[0]; } (The reassignments inside the if previously used their own instead of the other index.) --- "Back when I didn't trust my refactoring tools" Original code: for (unsigned tr0 = 0; tr0 < triangles0.size(); ++tr0) { if (std::find(triangles1.begin(), triangles1.end(), triangles0[tr0]) != triangles1.end()) return triangles0[tr0]; } After my change: for (unsigned tr0 : triangles0) { if (std::find(triangles1.begin(), triangles1.end(), triangles0[tr0]) != triangles1.end()) return tr0; } (Don't refactor absent-mindedly!)

eyelidlessness 6y ago
> Our linter would of course catch this, but it runs automatically only on the CI This is why, unless it’s a significantly degraded experience, I run a local watch version of what I expect to run in CI during dev. And if it is a significantly degraded experience I stop what I’m doing to either fix that (if possible) or refine it to at least approximate the CI validation automatically.

moron4hire 6y ago

Along this line of thinking (constant improvement), I made a big effort to excise the word "bug" in favor of "defect" in my speaking patterns. The word "bugs" implies that the issue got in from the outside, crawled into the works. It might even connote that it's a natural thing, that it has some sort of agency of its own. A "bug" is nobody's fault, unless someone's job was to keep the window closed and they failed at that job. The word "defect" is much more accurate. They were always there. That didn't just show up one day. They are an inherent artifact of a failure somewhere in the specification/design/development/testing process. Now, we might be generous and forgiving folk and not visit punishment on the person(s) who failed in that process, but that doesn't change the fact that it was a person who made the defect.

flippinburgers 6y ago

One more bug: not using vimwiki.

chaostheory 6y ago

This is pretty much what you need to do if you work for a US telecom. It felt like I spent more time with documentation than programming.

mjgs 6y ago

I could see this being a useful habit but if it’s just using vim and text files, it would be very tedious. I think you would need a tool to easily add, view and search to make it practical. Generally I like the idea of creating personal logs. I have a linkblog where I log all the important links I read: https://links.markjgsmith.com https://links.markjgsmith.com

bombastry 6y ago
In Emacs, an org-capture template[1] can be used to quickly and easily append new items to logs. It can prompt the user to enter text in multiple locations, eliminating the need to navigate around boilerplate to write entries. It can also prompt for tags to help make organization and searching easier. Additionally, it has the benefit of being callable anytime and anywhere within Emacs. I've only recently gotten around to using them, but they're really nice for quickly logging things that I was too lazy to do otherwise (e.g. recipes I have tried). [1]https://orgmode.org/manual/Capture-templates.html https://orgmode.org/manual/Capture-templates.html
- mjgs 6y ago
  That sounds kind of cool, though I’m not very familiar with emacs so it looks a bit strange to me. Does it essentially create the emacs equivalent of an html form, that you fill out and it then adds what you added to preconfigured text files, with the path to the file you were looking at when you triggered the template?
  - bombastry 6y ago
    Org-Capture creates a temporary buffer, inserts its template string, processes the special escape sequences (called "%-escapes")[1], and then lets the user edit the buffer before adding it as an entry. Where the entry goes is specified by the code that sets up the template. The power here comes from the %-escapes, which range from asking the user for a prompt and pasting it in that location ("%^{PROMPT}") to arbitrary code execution ("%(EXP)") that can include text input from the user from other %-escapes. There are escapes to insert the file name ("%f") and the full file path ("%F") of the file that was visited when the template was triggered. I think it's a lot easier to evaluate this kind of thing in action rather than in screenshots, so I've added an example screen recording[2] with a keylogger to show what a capture using a fairly simple template looks like. This Imgur album has both the screen recording as well as what the resulting entry looks like after it is saved. [1]https://orgmode.org/manual/Template-expansion.html https://orgmode.org/manual/Template-expansion.html [2]https://imgur.com/a/l8jwbnN https://imgur.com/a/l8jwbnN

spc476 6y ago

Starting back around 2009, I started marking bug fixes in git with the first line containing "Bug fix---description". For example (from my gopher server [1]): a12c3fd Bug fix---sample forgot POST method. 0b1bce2 Bug fix---grab guid when only given numeric uid. 31408da Bug tracking---crash because filename is nil? d993265 Bug fix---Clean the display text to prevent broken index files. 47e98e8 Bug fix---line comments were broken in .port70 files. I do the same at work. I got the idea from Donald Knuth, who wrote a paper about classifying each error in TeX [2]. I didn't go as far as he did, but I still have his list handy: * Algorithm * Blunder * Cleanup * Data * Efficiency * Forgotten * Generalization * Interaction * Language * Mismatch * Portability * Quality * Robustness * Surprise * Typo [1] https://github.com/spc476/port70 https://github.com/spc476/port70 [2] "The Errors of TeX" <https://yurichev.com/mirrors/knuth1989.pdf https://yurichev.com/mirrors/knuth1989.pdf>

l0b0 6y ago
Very similar to Conventional Commits[1], with this structure: <type>[optional scope]: <description> [optional body] [optional footer(s)] It's supported by pre-commit[2], which is an excellent way to set up commit rules and linting. [1] https://www.conventionalcommits.org/en/v1.0.0/ https://www.conventionalcommits.org/en/v1.0.0/ [2] https://pre-commit.com/ https://pre-commit.com/
- auslegung 6y ago
  At first, conventional commits sounds neat because they say you can > Automatically generating CHANGELOGs. > Automatically determining a semantic version bump (based on the types of commits landed). And I would really like those features. However it seems like this assumes 1 commit per feature, which I think is not the conventional wisdom. Am I missing something? For example, the feature is to add a new page to the site where the user can view all their posts. That should break down into several commits: add new route, add parser on frontend, add html structure, etc. But each of those commits would have to start with `feat: add route to fetch user's posts` and so on. Wouldn't that result in a unhelpfully verbose changelog, when the changelog should really feature one line: "Allow users to view all of their posts in one place"

itsmemattchung 6y ago

I 100% agree with the blog post, that everyone should collect a journal of bugs. However, looking at the author's example, I can't help but think that the "fix" for the bug is really just a good intention. More specifically, they were bitten by a bug where an environment variable wasn't set in production. Checking that the environment variable, in the future, is set is a nice next step however, I would say, another take away would be to encode that intention in the code directly: throw an error, emit a metric, log an error (that hopefully gets monitored).