banjo/backlog
Kevin d'Orange b211272e6e
All checks were successful
C++ Compatibility / C++ Compatibility Check (push) Successful in 21s
Documentation / build-docs (push) Successful in 22s
QA / cert (push) Successful in 50s
Build and Test / linux-linux-gcc / shared (push) Successful in 1m0s
Build and Test / linux-linux-gcc / static (push) Successful in 1m2s
Build and Test / linux-windows-mingw (build only) / shared (push) Successful in 55s
Build and Test / linux-windows-mingw (build only) / static (push) Successful in 57s
chore(backlog): small feature ID fixes (#204)
Reviewed-on: #204
2026-11-15 23:48:42 +01:00
..
feat-path chore(backlog): populate the backlog with initial content (#202) 2026-11-15 23:42:14 +01:00
feat-str chore(backlog): small feature ID fixes (#204) 2026-11-15 23:48:42 +01:00
feat-txt chore(backlog): small feature ID fixes (#204) 2026-11-15 23:48:42 +01:00
feat-atlas.md chore(backlog): populate the backlog with initial content (#202) 2026-11-15 23:42:14 +01:00
feat-renderer.md chore(backlog): populate the backlog with initial content (#202) 2026-11-15 23:42:14 +01:00
README.md chore(backlog): populate the backlog with initial content (#202) 2026-11-15 23:42:14 +01:00

Banjo Backlog

This folder contains the list of unresolved intentions, shaping the future of Banjo API, outside of any roadmap or release plan.

An unresolved intention is any future work item, regardless of its maturity or level of detail. It can be a rough idea, a draft, a refined story, a bug description, or anything in between.

Following ADR 0013, each backlog item is represented by a file or directory under this folder. A work item can be split into several smaller ones, in which case its composition is expressed as a directory containing the corresponding files and subdirectories.

This is a free-form backlog, which means:

  • Contrary to ADRs, files and directories in this folder can change at any moment, both in name, type and content.
  • The absence of a topic in this folder does not necessarily mean the work item will never be addressed.
  • The presence of a topic in this folder does not commit the project to its implementation.

Working with the Backlog

Draft: When you have a new feature idea, create a file for it in this folder. Use a simple name, and populate the file with whatever description fits the idea.

Refine: With time, you can edit the file, rename it, or split it into a directory containing multiple files.

Implement: When working on an item, the pull request that implements it must delete the file that describes the work item. If it was split into several sub-items, it is preferable to create one pull request per sub-item, and delete the parent directory once it becomes empty.

Useful Commands

The backlog is a collection of regular repository files. Standard Git and POSIX shell commands can therefore be used to manipulate, search, categorize and inspect it.

The following examples assume the current working directory is the repository root.

Creating and Listing Items

Purpose Command
Create an item mkdir -p backlog && touch backlog/my-new-idea.md
Create a subdivided item mkdir -p backlog/my-new-idea
List all Markdown files find backlog -type f -name '*.md' | sort
List top-level items find backlog -mindepth 1 -maxdepth 1 -print | sort
Count top-level items find backlog -mindepth 1 -maxdepth 1 | wc -l

Searching and Categorizing

Purpose Command
Search item content grep -Rni --include='*.md' 'unicode' backlog/
Search item names find backlog -iname '*unicode*'
List item names find backlog -mindepth 1 -maxdepth 1 -print | sort

Editing Items

Purpose Command
Open an item for editing "$EDITOR" backlog/my-idea.md
Rename an item git mv backlog/old-name.md backlog/new-name.md
Move an item into a directory git mv backlog/my-idea.md backlog/parent-item/my-idea.md
Rename a subdivided item git mv backlog/old-name backlog/new-name
Check backlog changes git diff -- backlog/
Check staged changes git diff --cached -- backlog/
Check repository status git status --short -- backlog/
Remove an item git rm backlog/my-idea.md
Remove a subdivided item git rm -r backlog/my-idea/

Inspecting Backlog History

Git can be used to inspect not only the current backlog, but also its previous states. This is particularly useful when trying to understand how an idea evolved or when an item was removed.

Purpose Command
Inspect an item's history git log --follow --oneline -- backlog/my-idea.md
Follow an item's evolution git log --follow -p -- backlog/my-idea.md
Show renames and moves git log --follow --name-status -- backlog/my-idea.md
Inspect a directory's history git log --oneline -- backlog/my-idea/
Inspect all backlog changes git log --oneline --all -- backlog/
List items at a commit git ls-tree -r --name-only COMMIT -- backlog/
Compare two backlog states git diff COMMIT_A COMMIT_B -- backlog/
Find changes to a term git log --all -S'unicode' --oneline -- backlog/
Read an item at a commit git show COMMIT:backlog/my-idea.md

The --follow option attempts to track an individual file across renames and moves. Git detects renames heuristically, so this is not guaranteed in every case.

Finding Deleted Items

Deleted items are not necessarily lost. As long as their commits remain reachable, Git can still be used to find and inspect them.

Purpose Command
List all deleted items git log --all --diff-filter=D --name-only --format= -- backlog/ | sort -u
Find deleted items by name git log --all --diff-filter=D --name-only --format= -- backlog/ | grep -i 'unicode'
Show deletion commits git log --all --diff-filter=D --oneline -- backlog/
Find deleted items mentioning a term git log --all --diff-filter=D -G'unicode' --name-only --format= -- backlog/ | sort -u

The --diff-filter=D option selects deletion events. The --all option searches commits reachable from all locally available references. The -G option searches for changes to lines matching a regular expression, rather than searching filenames.

Recovering Deleted Items

An item can be inspected or restored from the commit immediately preceding its deletion.

Purpose Command
Inspect an item before deletion git show COMMIT^:backlog/my-idea.md
Restore an item before deletion git restore --source=COMMIT^ -- backlog/my-idea.md
Inspect a deletion commit git show COMMIT -- backlog/

In these examples, COMMIT is the commit that deleted the item. COMMIT^ refers to its first parent, where the item still existed.

The restore command puts the recovered file in the working tree without staging it or creating a commit.

These commands are examples, not additional tooling requirements. They rely on Git and commonly available shell utilities.

Git history is not a permanent archive. The commands above can only inspect commits reachable from locally available references, and history rewriting or garbage collection can make previous items unrecoverable.