Using Devlogs in Practice
#workflows #open-source #projects
In an earlier post Avoid Project Management Tools in Solo Development, I mentioned how using formal project management tools for solo development can be more busywork than is worth when compared to a simple logging framework or file. In order to formalize this working style, I built a Ruby gem to help myself called
What is devlogs?
The idea is straightforward: a project based logging CLI that uses files co-located in the source code repository.
cd my_project devlogs init Creating devlogs repository... What is the project name? Test project What is the project description? Test project description What is the project short code (3 letters)? TST Do you want to mirror these logs? y Path to mirror directory: $HOME/src/my_project/devlogs-mirror Created devlogs repository
The above initialization process creates a hidden directory called
.devlogs inside of the project. Inside the
.devlogs repository there are a few different files:
.devlogs/ issues/ .devlogs.config.yml .devlogs.data.yml .issue_template.erb.md .log_template.erb.md test_project.devlogs.info.md
.devlogs.config.yml contains the configuration information provided in the initial setup including
mirror configuration. The mirroring functionality exists for the use case in which you do not want to commit logging to version control but want to maintain a copy somewhere else on your computer that you backup. For example, I might manage project information inside of an Obsidian project folder, and want to mirror all the logs there for posterity.
.devlogs.data.yml file contains state data required for operating the CLI. At the moment, it is just a store for incrementing the issue index for a new issue. For example
TST-2, et cetera.
.log_template.erb.md file is an optionally customizable template file that the
devlogs CLI will use for creating each log entries. This is useful if you have a custom scheme which you tag notes in your Obsidian vaults or other project management software.
.issue_template.erb.md file is similar to the log template file. It is a customizable template you can use for tracking various issues for your project. I added issue tracking because my logging workflow seemed to always be at the end of my development period (e.g. finishing work for the day) but I wanted to have a way of capturing in-the-moment bugs or other issues that were unrelated to my present task that I didn’t want to forget about.
test_project.devlogs.info.md is just an
.info file. This is preferential to my workflow in Obsidian containing the project description.
Using devlogs for logging
When you are done developing for the day you can use the
devlogs new command to create a new entry. Here is an example below from a project:
# LOG: 09-28-2022 15:43 Tags: #dev, #log - Decided to go ahead and start with importing audio before configuring the ui. - I was implementing of repository pattern, but not sure if it's the right direction. Need to think a little more about this NEXT: - Need to find an ID3Tag reading library. This will help to read the metadata from an MP3 thereby allowing import into the application.
As you can see the notes are informal and meant only to capture the context at the time and the top of mind items for your next development session.
You can use the
devlogs ls command to explore previous log entries or
devlogs last in order to get the most recent entry:
devlogs ls Select a log entry... (Press ↑/↓ arrow to move and Enter to select) ‣ 09-28-2022__15h43m_log.md ‣ 09-27-2022__12h41m_log.md
Using devlogs for issues
devlogs also helps with local issue tracking. New issues can be created via
devlogs new_issue which will prompt you for some information, read from the issue template and open the file in an editor for you to confirm and save.
# TST-1: There is a problem ## Problem When I try to use the project it errors out! ## Reproduction Steps Open the project and run ./bin/run
Issues are contained in the
issues sub directory of
.devlogs. You can explore the issues via
Select an issue issue... (Press ↑/↓ arrow to move and Enter to select) ‣ tst-1__there_is_a_problem.md
devlogs CLI uses the convention of 3-letter-prefix + index in order to create keys for issues.
I have some future ideas of features to add to
devlogs but hope to keep it rather simple and maintainable. If you use it and have feedback please let me know.