arkadianriver/hqtodo

See your Todo list as a Gantt chart, view your velocity, and review finished items by week and by tagged category.

hqTodo

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 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).

Features

• Open items and their estimates are used to display a Mermaid Gantt chart. Tasks shift with time, starting from now into the future, providing a quick glimpse of probable completion dates.

• 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 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.

1. Set things up.

   1. 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.

   2. Install server dependencies:

      npm install

   3. Install client dependencies and build it:

      cd client-react-carbon
      npm install
      npm run build
      cd ..

2. Thereafter, run the app with …​

   ./run

   ... and point your browser to http://localhost:3000.

   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.

Maintaining your todo file

For the most part, update your TODO file as you normally would. There are a few conventions to use for the app to work. 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:

☐ [@today|@high|@low] <todo description> [@Nh] [@custom ]*

• Priority tagging:

  • Items prefixed with @today are placed in order in the “In Progress” section.

  • Items with no priority label are listed in order in the “Backlog” section.

  • Items prefixed with @high are colored red.

  • Items prefixed with @low are not displayed. (This is your Icebox.)

• The optional @Nh tag indicates your estimated N hours. No tag gets the default of 2 hours.

• You can provide any number of @custom tags for your own custom filtering. They’re simply displayed with the title.

• When you press Super+D to mark a task with a checkmark and a @done tag, it’s listed in the “Recently closed todos” section of the web page.

Example:

☐ @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:

☐ [Nd starting YYYY-MM-DD]: <title>

Example:

☐ [5d starting 2020-05-18]: Whiz-Bang-Boom conference

Milestones

Milestones have the same form as an interrupt, but with a length of zero days (0d).

Example:

☐ [0d starting 2020-06-15]: Complete Project A @proja

Milestones show up in their own section above the others.

Referencing a GitHub repo

If you reference a particular issue in your todo text (for example if you use the linkme VS Code extension), the Gantt chart will link to the issue from the task bar and todo text.

Edit the config file repo URL to point to your own repo. As set up now, it has two patterns:

• one pattern that links to the default repo that you specify in the config file ghihq•4

• one pattern that links to whatever repo you specify in the todo file itself ghi•ragnoroct/linkme•9

You can of course change the patterns to link to whatever you want.

Archived todos

If you archive your done items (e.g. Cmd+Shift+A]), they will be available at the bottom along with a graph of the cumulative story points you’ve knocked out over time. Marvel at your progress!

💡	Use category tags in your todo items to see them grouped and totaled by category.

The taginfo section

Use this section if you want to provide a more descriptive title and link to more information on the project.

The structure of each entry:

☐ @tagname full title of the project or category - url or linkme link

Example:

☐ @prja Project A - den•bRNzBMOVaqYl6i7C.html

I personally link to pages published with Dendron, because I like to also use VS Code for my note taking, and Dendron has a cool feature where you can publish Notes to a web site.

What’s next?

See the @hq project in the Classic-styled hqTodo file.

hqtodo's Issues

axisTop would be useful for long todo lists

See D3 documentation https://github.com/d3/d3-axis/blob/v1.0.12/README.md#axisTop

support "blockers"

When TODOs are blocked because you're waiting for something, move them out of and above the active workflow temporarily and indicate what you're waiting on.

Use a tag because it's easy to add and edit/remove. Support multiple blockers per item. Using format @blk.<method>.<person>. For example @blk.email.alex.

Still display duration of task so you know what you're up against, but not in cascade. Add a popup that shows what you're waiting on. Since the only mermaid event handler is 'click', move blocker links into the popup if they exist.

archive byTag

new endpoint to take archived results, group them by tag, and return:

[{
  tag: "woot",
  totalPoints: 13.5,
  titles: [
    "this thing",
    "that thing",
    "the other thing"
  ]
}, ... ]

Display that as another collapsible list at the bottom of the page or in another view, particularly the "woot" category

needs test cases

add milestones to Gantt

Just to have important dates visible on this thing as reminders.
No tracking of slipped dates or anything.

maybe similar notes as interrupts, but preserving tags and no durations (make 2 hr to see the red)

☐ [milestone on 2020-07-04] Fourth of July party @personal

htmlencode certain special chars

Replace chars that break mermaid with the HTML symbol instead, such as the # character (not comments, but when used in a sentence)

live links in archive, too

add :active color for github-linked todos

consider rendering from the client

Have client keep itself updated by pulling from the APIs and rendering its own page instead of a static one made by express and EJS. Axios!

Besides not having to click refresh, JSON data in the client opens front-end possibilities. To filter tags to see particular projects highlighed, for example (if not in mermaid, maybe another view).

escape `:` and `#` in mermaid entries (but not links)

support links to github

• Use similar configs as the linkme extension to define the RegExps to search for
• add click entries to the mermaid Gantt chart

sort descending closed items

[feature]: hide Left/Right buttons when not enough tags

There are two left/right arrow buttons in hq-tag-row that do not appear to have a function. Expected behavior may be to cycle through selected tags or periods of time?

PS This is great, thank you for sharing your work!

no archive results in error

@epic tags

Report @woot items in a more meaningful way, perhaps by adding an @epic tag and displaying in a new section on the main page. Somehow representing active epic groupings would be useful, too, in addition to completed ones .. including the running total of storypoints/hours remaining/completed.

In todo+ extension view, the data might look like this:

Todos:
  ...
  Project to create something fabulous ghic•112:
    ☐ @today apply x toward fabulous thing @epic.somefab @prjx
    ☐ fetch that y thing @epic.somefab @1h @prjy
    ☐ take z and morph it with something fabulous @4h @epic.somefab @prjz
  ...

Archive:
  ✔ added `a` to fabulous @2d @epic.somefab @prja @done(2021-07-24 20:00) @Project(Todos.Project to create ...)
  ✔ test b for fabulous (rejected) @3h @epic.somefab @prjb @done(2021-07-20 11:08) @Project(Todos.Project to create ...)
  ...
  ✔ apply p to project excellence @1d @epic.excellence @prjp @done(2021-07-01 17:22) @Project(Todos.Project to create ...)

In hqTodo, could then collect all @epics grouped in todos/archives as usual for normal reporting, but additionally grouped in a new data set by the epic tag's extended .<epic-id> (somefab in this case). With that, a report might look something like this:

EPICs:

Active work:

• somefab (2.5 pts) [expand/collapse]

Completed work:

• 2021-07-24: somefab (5.5 pts) [expand/collapse]
• 2021-07-01: excellence (4.0 pts) [expand/collapse]

rm Todo+'s project tag from the archive listing

"tag activity" as bar chart instead

unlike the home page "overall performance" chart, tag charts serve more of a when did I last work on it and is it really closed kind of thing.
.. but like the home page possibly go to beginning of the year as well, to align the calendars. Test how it looks to see.

fix overlaps when inserting interrupts

I'm pretty sure its the way weekdays are calculated: skipped for interval between interrupts, but not for interrupt duration.

track support calls

Using Todoplus' start and done timer function, collect support calls in the archive and display a bar chart by project.

As items come in, add them to the Support: top level section in the file

Support
  ☐ Help do this and that @projA

Use the Super-s and Super-d features of Todoplus to start and stop the timer. When you archive your todos, these will end up in the same archive.

Archive:
  ✔ Help do this and that @projA @started(2020-06-16 06:44) @done(2020-06-16 07:04) @lasted(20m33s) @project(Support)

Because the todo archive ignores anything outside of the Todos project, create a new function that solely pulls the @project(Support archive items into a list where you can aggregate the lasted times (or calculate start done yourself.. whatever's easier with moment.js) by @tag
Expose those aggregates with an endpoint that can be used by the front-end to display a bar chart of time spent supporting each project over the last X days. Or something like that.. haven't decided yet.

put hours back in _recently closed_ list

They were converted for Gantt chart and they're still that way. Put back to normal.
Or better, convert to story points with a configuration option of what you consider to be a story point. (ie. "storyPointsPerDay": 2)

Might eventually opt to going back to recording story points instead of hours with "hoursPerStoryPoint": 12 instead.

needs error handling

read file /^Archive:/ section for "See more..." done

add date to home page title

Maybe remove top ellipsis and add a secondary heading that says

from YYYY-MM-DD to today ...

or something like that. The whole thing needs an updated complete Carbon look-and-feel eventually

Math .. ∫𝑓(𝑥) 𝑑𝑥 .. show your work! ☺

Something's amiss in the tag page hour calculations.

So, fix that, and comment (in the code) what the hell you're doing with the conversions so it's easier to fix next time something like this happens. Also explain (in the readme) the point of the story point options and why a day doesn't always equal 8 hours and a story point isn't always just one per day.