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.
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.
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.
> 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.
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'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.)
> 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.
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.
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:
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).
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?
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.
It’s intersecting to get an idea of how to quickly do logging from within a code editor.
My linkblog uses a web app, with a bookmarklet frontend, so it’s easy to post when browsing the web from inside the browser.
But for a bug log it makes sense to be adding directly from the editor, though I could imagine that having a way to add entries using a web form might be useful too, making it possible to use touch screen devices.
There are a number of different ways to do this in Emacs, but org capture is probably the place to start. This feature is very powerful. See [1].
> That sounds kind of cool, though I’m not very familiar with emacs so it looks a bit strange to me.
Yes, Emacs is an editor from another time and is a bit strange.
Like Vim/vi, Emacs has survived for something like 44 years. There have been hundreds of text editors created and used, some very widely, over the intervening decades.
Through a kind of evolutionary pressure, better editors survive and less capable editors decline in popularity. The best features are often adopted by the newer generations of text editors. By now, there are a pretty widely accepted set of features in modern editors, for example cut-copy-paste and undo. But, like the octopus, Emacs and Vim are just different than other creatures. Not necessarily better in every way, but different. So cut-copy-paste is supported by these editors if you insist, but they have their own highly refined way of improving even these elementary and widely used operations.
I like VS Code, Sublime Text, and Jet Brains IDEs; however, the editor I use the most is Emacs. It is, at the core, a set of low level primitives for editing text combined with a flexible programming language interpreter that higher level commands use to implement its unbelievable feature set. By now, millions of lines of code have been contributed to Emacs and it is likely to have whatever you want out of an editor.
There is a bit of a bump to get over when learning either one of these two paleolithic editors (Emacs or Vim). If you are a coder, I think it worth learning at least one of these two proven editors.
Thanks for the elaboration, your description of vim and emacs as paleolithic editors made me smile.
I was introduced to vim a long time ago at a previous company, and so I went that route rather than emacs. I’m moderately good at vim now, but VSCode is just much easier to use.
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:
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"
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).
27 comments
[ 3.3 ms ] story [ 64.2 ms ] threadThe 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.
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
When you can do this openly it helps build a public body of work that can earn you better jobs.
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.
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.
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.
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 ;)
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..."
(Our linter would of course catch this, but it runs automatically only on the CI.)---
"Variables change when they are assigned!"
(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:
After my change: (Don't refactor absent-mindedly!)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.
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.
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
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
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?
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 [2]https://imgur.com/a/l8jwbnN
My linkblog uses a web app, with a bookmarklet frontend, so it’s easy to post when browsing the web from inside the browser.
But for a bug log it makes sense to be adding directly from the editor, though I could imagine that having a way to add entries using a web form might be useful too, making it possible to use touch screen devices.
> That sounds kind of cool, though I’m not very familiar with emacs so it looks a bit strange to me.
Yes, Emacs is an editor from another time and is a bit strange.
Like Vim/vi, Emacs has survived for something like 44 years. There have been hundreds of text editors created and used, some very widely, over the intervening decades.
Through a kind of evolutionary pressure, better editors survive and less capable editors decline in popularity. The best features are often adopted by the newer generations of text editors. By now, there are a pretty widely accepted set of features in modern editors, for example cut-copy-paste and undo. But, like the octopus, Emacs and Vim are just different than other creatures. Not necessarily better in every way, but different. So cut-copy-paste is supported by these editors if you insist, but they have their own highly refined way of improving even these elementary and widely used operations.
I like VS Code, Sublime Text, and Jet Brains IDEs; however, the editor I use the most is Emacs. It is, at the core, a set of low level primitives for editing text combined with a flexible programming language interpreter that higher level commands use to implement its unbelievable feature set. By now, millions of lines of code have been contributed to Emacs and it is likely to have whatever you want out of an editor.
There is a bit of a bump to get over when learning either one of these two paleolithic editors (Emacs or Vim). If you are a coder, I think it worth learning at least one of these two proven editors.
[1] https://www.youtube.com/watch?v=qCdScs4YO8k
I was introduced to vim a long time ago at a previous company, and so I went that route rather than emacs. I’m moderately good at vim now, but VSCode is just much easier to use.
* Algorithm * Blunder * Cleanup * Data * Efficiency * Forgotten * Generalization * Interaction * Language * Mismatch * Portability * Quality * Robustness * Surprise * Typo
[1] https://github.com/spc476/port70
[2] "The Errors of TeX" <https://yurichev.com/mirrors/knuth1989.pdf>
<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/
[2] https://pre-commit.com/
> 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"