|
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
Reviewed-on: #204 |
||
|---|---|---|
| .. | ||
| feat-path | ||
| feat-str | ||
| feat-txt | ||
| feat-atlas.md | ||
| feat-renderer.md | ||
| README.md | ||
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.