docs: add scripted demo gifs (board + stats) to the README - #47
Merged
Conversation
The README showed the logo but never the board. assets/demo.tape records one with vhs: it seeds a throwaway board under mktemp -d, then walks the board, adds an item that inherits the cursor row's category, ticks it off, opens the detail view and tags it from there, cycles the views, and filters. CONTRIBUTING.md documents how to regenerate it.
The board recording seeded items with shepherd add, so every chart in shepherd stats was flat: everything created today, nothing completed. assets/demo-seed.sh writes the board and its archive directly, with dates relative to the recording day, so the sparkline, backlog trend and aging numbers all have something to draw. assets/stats.tape records shepherd stats over that board (smaller font: the output is 56 rows) and the README embeds it in the command-api section.
jwarykowski
changed the title
stats had a paragraph buried in the command api, between the mutation verbs and the list --json example, with its colour rules stranded in the exit-code paragraph. Pull it into its own section: the gif, a flag table, and what the backlog health line means. Also moves the contents list above the defaults table, so the index comes before the content, and drops the claim that the board has a stats page — only the CLI does.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The README showed the logo but never the board, and never the charts.
Two recordings, both scripted with vhs rather than screen-captured, so they can be regenerated after any layout change:
assets/demo.gif(1320x760, ~29s, 792K) — the boardassets/stats.gif(1400x1000, ~7s, 116K) —shepherd statsseeding
assets/demo-seed.shwrites both the board and its archive directly, with all dates relative to the recording day. Seeding viashepherd add(the first attempt) left every chart flat — everything created today, nothing completed — sostatshad an empty sparkline and no backlog trend. The archive now carries 11 completed items spread over 26 days, and one open item is deliberately 38 days old to exercise the stale tail.Both tapes point
SHEPHERD_TODO_FILE/SHEPHERD_CONFIGat amktemp -d, so recording never touches a real board or config.shot list (board)
jdown the rowsaadd "write the release notes" — inheritsreleasefrom the cursor rowspacetick it offddetail view, thenTto tag it, with the editor rendering over the detail viewvcycling category / priority / tag / table views/releasefilterqCONTRIBUTING.mdgains a section on regenerating both.Two notes for anyone editing a tape: interactive zsh eats the
!h/!lpriority tokens as history expansion, which is part of why the seed writes markdown directly instead of shelling out toshepherd add; and each recording's height has to clear its tallest screen — the priority view for the board, 56 rows forstats.