= hqTodo :experimental: :toc: :toc-placement!: ifdef::env-github[] :tip-caption: :bulb: :note-caption: :information_source: :important-caption: :heavy_exclamation_mark: :caution-caption: :fire: :warning-caption: :warning: endif::[] ifndef::env-github[] :icons: font endif::[]
pass:[
If you love keyboard shortcuts and things like Org mode, you might like hqTodo to present your complete agile workflow from one easily editable Todo list in VS Code. Rather than drag cards around and click and open various windows, use Fabio Spampinato's link:https://github.com/fabiospampinato/vscode-todo-plus[TODO+ extension] to capture status, categories, and estimates as individual todo items in a text file, with keyboard shortcuts to prioritize and close issues. His extension is awesome, and with this li'l hqTodo web app, all that information is summarized in an easily consumable report for you (and your team if you want).
pass:[
//// pass:[
== Features
- Open items and their estimates are used to display a https://mermaid-js.github.io/mermaid/#/gantt[Mermaid] Gantt chart. Tasks shift with time, starting from now into the future, providing a quick glimpse of probable completion dates.
- https://apexcharts.com/[ApexCharts] is used to display cumulative story points you've knocked out to help keep track of your velocity.
- If you field support questions, you can also track those with the TODO+ extension and view the cumulative time spent in the chart.
- Completed items are displayed underneath. Great for weekly status reports.
- Tag your items to provide a detailed status page for each project.
- Because everyone else uses other forms of tracking, I use the link:https://marketplace.visualstudio.com/items?itemName=ragnoroct.linkme[Link Me extension] to include shortcuts to all those other resources in my Todo list. The hqTodo app exposes those links, too.
== Running the app
Prereq: NodeJS v12 or higher.
. Set things up.
.. Copy the config/default.json file to config/production.json
and add your info to the new file.
Your own TODO file can be anywhere on the file system the app can access,
such as a shared Cloud or Network mounted folder.
.. Install server dependencies:
+
[source, bash]
npm install
.. Install client dependencies and build it: + [source, bash]
cd client-react-carbon npm install npm run build cd ..
. Thereafter, run the app with ... + [source, bash]
./run
+
... and point your browser to http://localhost:3000.
+
kbd:[Ctrl+C] stops the server.
One way to deploy the app in "production" is to run it on a server with pm2, systemctl, etc., and add your TODO file to a folder on the server that's synced with your local workstation with SyncThing or similar cloud folder sync application.
//// == Deploy
For example with systemd on Linux:
[source,bash]
vi misc/hqtodo.service # change the absolute paths and user sudo cp misc/hqtodo.service /etc/systemd/system/ sudo systemctl start hqtodo sudo journalctl -f # to verify. Also test in a browser sudo systemctl enable hqtodo
////
== Maintaining your todo file
For the most part,
link:https://marketplace.visualstudio.com/items?itemName=fabiospampinato.vscode-todo-plus#usage[update your TODO file]
as you normally would.
There are a few conventions to use for the app to work.
link:TODO[See the sample TODO file]
as an example.
Everything in your TODO file is ignored except ...
- the list in the optional
Taginfo:section - the todo items between the
Todos:project and the next top-level project. - the todo items after
Archive:
... where a todo item is a line starting with ☐ or ✔.
=== Active todo items
Syntax:
[source,bash]
☐ [@today|@high|@low] [@Nh] [@custom ]*
- Priority tagging:
Items prefixed with
@todayare placed in order in the In Progress section. Items with no priority label are listed in order in the Backlog section. Items prefixed with@highare colored red. Items prefixed with@loware not displayed. (This is your Icebox.) - The optional
@Nhtag indicates your estimated N hours. No tag gets the default of 2 hours. - You can provide any number of
@customtags for your own custom filtering. They're displayed with the title. - When you press kbd:[Super+D] to mark a task with a checkmark and a
@donetag, it's listed in the "Recently closed todos" section of the web page.
Example:
[source,bash]
☐ @high Work with so-and-so on such-and-such @4h @prja @prjb
=== Interruptions
You can let folks know about vacations and other "interruptions"
to your steady velocity.
Specify the duration and start date as business days only.
Syntax: