Why I keep a personal log of bugs
josemdev.com
josemdev.com
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.
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.
* 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.
> 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"
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.
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.
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;
---
"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];
}
---
"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];
}
for (unsigned tr0 : triangles0)
{
if (std::find(triangles1.begin(), triangles1.end(), triangles0[tr0]) != triangles1.end())
return tr0;
}
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.
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 ;)
Generally I like the idea of creating personal logs. I have a linkblog where I log all the important links I read:
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).
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.
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.