Tracking progress

When working on an application, how do you maintain structure and track your progress? This is a question with many answers. For solo-devs, one might keep a physical notepad handy - for teams and open-source projects, Github or a third-party todo application might make more sense.

What about me then? I'm an old-school guy that likes simplicity. My two main methods the last couple years have been: 1, TODO comments inside my codebase that I can find using the grep command, or 2, a todo.md file where I keep a list of ongoing problems and notes. And while these two methods have worked, I don't like the friction they create - my workflow is obstructed by constantly having to jump back and forth between a todo-list and my codebase. Yet I've kept applying these methods since using a dedicated todo-list application or something similar would (arguably) be even worse; I'm a solo-developer building simple programs and would have no use for an advanced issue-tracking solution.

But I happened to find a video on youtube a few days ago that gave me a burst of inspiration. While the todo application presented in this video didn't suit my taste, it did however give me an idea: "what if there is no separate todo.md file or sporadic TODO comments, but instead a mix of the two?", "what if the todo-list sits inside the codebase itself?".

An issue-tracker

I got to work, and within a day I had built something I really liked - an opinionated issue-tracker designed for the typical solo-dev workflow. It's called 'Brakoll' and I want to talk about it a little in this blog entry!

If you want to try the application yourself or read the documentation, check it out on Github.

As I mentioned in the initial section, the core philosophy of Brakoll is to keep all the on-going issues and notes within the codebase. My belief is that this philosophy solves the following common problems:

1. Your codebase will be more portable - you can move it all to a new computer or send it to a friend with all its on-going issues included.
2. There are no extra directories, files or environments to maintain - Brakoll keeps no cache or perpetual memory, nor does it use a configuration file. No baggage.
3. You don't need an internet connection, it's all local!
4. No jumping between different files, everything is done directly in your codebase and Brakoll's CLI.

The easy way out

But creating an application that solves these problem isn't enough, it obviously also needs to fit within and around all the other tools a developer uses every day. And if I someone says "development tool" to me, the first tool I think of is git. Another annoying piece of friction I experience daily is writing git commit messages - I want my commit messages to look nice, and so perhaps this could also be dealt with using Brakoll?

To integrate Brakoll with git, I created a 'copy' command. This copies the contents of a todo item and adds it to the clipboard. "Okay, what's the big deal?" I hear you ask. With a simple bash script attached to an alias I can make git commits a thousand times less of a headache:

unalias commit 2>/dev/null
commit() {
    local id="$1"
    brakoll close $id
    brakoll cp $id

    if command -v pbpaste >/dev/null; then
        clip=$(pbpaste)
    elif command -v xclip >/dev/null; then
        clip=$(xclip -o -selection clipboard)
    elif command -v wl-paste >/dev/null; then
        clip=$(wl-paste)
    fi

    git add --all
    git commit -a -m "$clip"
}

The script above takes an argument "id" - in this case it's the id of an issue I want to close and commit. The rest of the code is self-explanatory.

Ok, what about the bigger picture? Brakoll has a subcommand 'summary' which condenses all issue items in your codebase into brief overview:

❯ b summary
Searching for issues...
20 issues were found.

tags
-------
11      : feature
4       : fix
4       : docs
1       : refactor

status
-------
17      : closed
2       : open
1       : in progress

My development workflow with Brakoll looks like this:

1. Create a new issue within the codebase.
2. When I want to work on the issue, I set its status to "in progress" either directly in the code or through the CLI.
3. Finish working on the issue.
4. Run command 'brakoll' (with relevant filter flags if necessary) to find its id number.
5. Run bash script 'commit <id>' to close the issue and commit it to git.
6. Run command 'brakoll summary' every once in a while to track my progress.
7. Rinse and repeat.

Ok, that's enough

I won't go over all the functions of Brakoll here. But chances are that if you've read this far, you are probably interested! If so, head to Brakoll's github page to get more details on how to install and use it.