automated release notes
This commit is contained in:
Willem van den Ende
parent
dfa1763e5e
commit
c70d904586
@ -0,0 +1,253 @@
|
||||
%{
|
||||
title: "Automated release notes with 'demo' skill",
|
||||
author: "Willem van den Ende",
|
||||
tags: ~w(ai),
|
||||
description: "Agents can make release notes, given the right tools and instructions. Showboat, Chrome DevTools MCP were quite easy to use. ",
|
||||
published: true
|
||||
}
|
||||
---
|
||||
|
||||
Yesterday, I added scheduled posts to firehose. I let my coding agent write the [release notes](blog/releases/scheduled-publishing). It is fun to read the release notes like this, and see the screenshots. Do note that a coding agent might not care there is no navigation - it happily will remember the urls and navigate to them, so that is something you might want to double check with exploratory testing :-).
|
||||
|
||||
I've included the full skill below. It is not in the repository, it went straight to my home directory so I can use it in other porjects. This is the second project I have used it in. It helped me earlier do a fairly large archiectural spike for an RFP response, and include screenshots of a working application in the response document. Working software is still a great measure of progress.
|
||||
|
||||
# Demo skill - let your agent generate demos with screenshots for you
|
||||
|
||||
---
|
||||
name: demo
|
||||
description: >-
|
||||
Generate a living demo document proving a feature works. Uses showboat
|
||||
for Markdown assembly with captured command output and rodney for Chrome
|
||||
browser screenshots. Use when the user says "demo this", "show me it works",
|
||||
"create a demo", or after /build completes.
|
||||
argument-hint: "<feature-name> [--scenario <description>] [--plan <path>]"
|
||||
user-invocable: true
|
||||
allowed-tools: Read, Write, Glob, Grep, Bash
|
||||
---
|
||||
|
||||
# Demo
|
||||
|
||||
Role: worker. This command generates a standalone Markdown demo document that proves a feature works, using showboat for document assembly and rodney for browser automation.
|
||||
|
||||
You have been invoked with the `/demo` command.
|
||||
|
||||
## Parse Arguments
|
||||
|
||||
Arguments: $ARGUMENTS
|
||||
|
||||
- Positional: `<feature-name>` (required) — short name or description of the feature to demo
|
||||
- `--scenario <description>`: Explicit demo scenario describing what to show. If omitted, infer from the plan and recent commits.
|
||||
- `--plan <path>`: Path to the plan file. If omitted, search `plans/` for the most recently modified `.md` file with status `implemented` or `approved`.
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Check tool availability
|
||||
|
||||
Verify showboat and rodney are installed:
|
||||
|
||||
```bash
|
||||
showboat --help 2>/dev/null && echo "showboat: ok" || echo "showboat: missing"
|
||||
rodney --help 2>/dev/null && echo "rodney: ok" || echo "rodney: missing"
|
||||
```
|
||||
|
||||
If either tool is missing, tell the user:
|
||||
|
||||
> One or more demo tools are missing. Install them with:
|
||||
> ```bash
|
||||
> go install github.com/simonw/showboat@latest
|
||||
> go install github.com/simonw/rodney@latest
|
||||
> ```
|
||||
|
||||
Do not proceed until both tools are confirmed available.
|
||||
|
||||
### 2. Gather feature context
|
||||
|
||||
Build an understanding of what to demo from these sources (in priority order):
|
||||
|
||||
1. **Explicit scenario** (`--scenario`): If provided, use as primary guide.
|
||||
2. **Plan file**: Read the plan's Goal, Acceptance Criteria, and completed Steps.
|
||||
3. **Recent commits**: Run `git log --oneline -15` and `git diff main...HEAD --stat` to identify changed files and commit messages.
|
||||
4. **Route map**: Cross-reference changed files against known LiveView routes in the router (`lib/hub_web/router.ex`).
|
||||
|
||||
From these sources, produce a **demo outline**:
|
||||
- **Narrative**: 2-3 sentence description of what the feature does
|
||||
- **Backend evidence**: mix commands, test output, or database queries to run
|
||||
- **UI pages**: which routes to visit and what to look for
|
||||
- **Interactions**: any clicks, form fills, or navigation sequences to perform
|
||||
|
||||
If no plan exists and commits are ambiguous, ask the user for a brief description of what to demo.
|
||||
|
||||
### 3. Check dev server
|
||||
|
||||
```bash
|
||||
curl -s -o /dev/null -w "%{http_code}" http://localhost:4000/ 2>/dev/null
|
||||
```
|
||||
|
||||
If the server is not reachable:
|
||||
|
||||
> The Phoenix dev server is not running. Start it now?
|
||||
> ```bash
|
||||
> mix phx.server &
|
||||
> ```
|
||||
|
||||
After starting, wait up to 10 seconds and verify connectivity. If it still fails, proceed with backend-only evidence (skip all browser screenshots) and note the limitation in the demo document.
|
||||
|
||||
### 4. Handle authentication
|
||||
|
||||
The app requires authentication for LiveView routes. Before capturing UI screenshots:
|
||||
|
||||
1. Ensure a demo user exists:
|
||||
```bash
|
||||
mix run -e "
|
||||
alias Hub.Accounts
|
||||
case Accounts.get_user_by_email(\"demo@example.com\") do
|
||||
nil -> Accounts.register_user(%{email: \"demo@example.com\", password: \"demodemo1234\"})
|
||||
user -> {:ok, user}
|
||||
end
|
||||
"
|
||||
```
|
||||
|
||||
2. Log in via rodney:
|
||||
```bash
|
||||
rodney start
|
||||
rodney open http://localhost:4000/users/log-in
|
||||
rodney wait "input[name='user[email]']"
|
||||
rodney input "input[name='user[email]']" "demo@example.com"
|
||||
rodney input "input[name='user[password]']" "demodemo1234"
|
||||
rodney click "button[type='submit']"
|
||||
rodney waitidle
|
||||
```
|
||||
|
||||
If login fails, warn and proceed with backend-only evidence.
|
||||
|
||||
### 5. Initialize the demo document
|
||||
|
||||
Slugify the feature name (lowercase, hyphens, no special chars). Then:
|
||||
|
||||
```bash
|
||||
showboat init "demos/demo-$(date +%Y%m%d-%H%M%S)-<slug>.md" "Demo: <Feature Name>"
|
||||
```
|
||||
|
||||
Store the demo file path for use in all subsequent steps.
|
||||
|
||||
### 6. Narrative introduction
|
||||
|
||||
```bash
|
||||
showboat note <demo-file> "## Feature Overview
|
||||
|
||||
<2-3 sentence description derived from the plan or commits.>
|
||||
|
||||
**Branch**: $(git branch --show-current)
|
||||
**Commits**: <N> commits ahead of main
|
||||
**Plan**: <plan file path or 'none'>
|
||||
"
|
||||
```
|
||||
|
||||
### 7. Backend evidence
|
||||
|
||||
Capture backend proof via `showboat exec`. Always include relevant tests. Add narrative notes between evidence blocks explaining what each proves.
|
||||
|
||||
**Test output** (always include):
|
||||
```bash
|
||||
showboat note <demo-file> "## Test Suite"
|
||||
showboat exec <demo-file> bash "mix test <relevant-test-files> --color"
|
||||
showboat note <demo-file> "All <N> tests pass, confirming <specific criterion>."
|
||||
```
|
||||
|
||||
**Compilation check**:
|
||||
```bash
|
||||
showboat note <demo-file> "## Compilation Check"
|
||||
showboat exec <demo-file> bash "mix compile --warnings-as-errors"
|
||||
```
|
||||
|
||||
**Database state** (if relevant to the feature):
|
||||
```bash
|
||||
showboat note <demo-file> "## Database State"
|
||||
showboat exec <demo-file> bash "mix run -e '<query expression>'"
|
||||
```
|
||||
|
||||
### 8. UI screenshots
|
||||
|
||||
For each UI page identified in step 2, navigate with rodney, screenshot, and embed via showboat.
|
||||
|
||||
**Static page capture**:
|
||||
```bash
|
||||
rodney open http://localhost:4000/<route>
|
||||
rodney waitidle
|
||||
rodney screenshot demos/screenshots/<feature>-<page-name>.png
|
||||
|
||||
showboat note <demo-file> "### <Page Name>
|
||||
|
||||
<What this page shows and why it proves the feature works.>"
|
||||
|
||||
showboat image <demo-file> ''
|
||||
```
|
||||
|
||||
**Interactive flow** (form submissions, navigation):
|
||||
```bash
|
||||
showboat note <demo-file> "### Interactive Flow: <Flow Name>"
|
||||
|
||||
# Before state
|
||||
rodney screenshot demos/screenshots/<feature>-before.png
|
||||
showboat image <demo-file> ''
|
||||
|
||||
# Perform interaction
|
||||
rodney click "<selector>"
|
||||
rodney input "<selector>" "<value>"
|
||||
rodney click "<submit-selector>"
|
||||
rodney waitidle
|
||||
|
||||
# After state
|
||||
rodney screenshot demos/screenshots/<feature>-after.png
|
||||
showboat image <demo-file> ''
|
||||
```
|
||||
|
||||
### 9. Acceptance criteria checklist
|
||||
|
||||
If a plan file exists, map each acceptance criterion to evidence:
|
||||
|
||||
```bash
|
||||
showboat note <demo-file> "## Acceptance Criteria Verification
|
||||
|
||||
- [x] <Criterion 1> -- see Test Suite output above
|
||||
- [x] <Criterion 2> -- see <Page Name> screenshot
|
||||
- [x] <Criterion 3> -- see Database State output
|
||||
"
|
||||
```
|
||||
|
||||
If no plan, summarize what was demonstrated and what it proves.
|
||||
|
||||
### 10. Clean up
|
||||
|
||||
```bash
|
||||
rodney stop 2>/dev/null || true
|
||||
```
|
||||
|
||||
### 11. Report results
|
||||
|
||||
Display:
|
||||
```
|
||||
## Demo Complete
|
||||
|
||||
- **Document**: demos/<filename>.md
|
||||
- **Screenshots**: <N> captured in demos/screenshots/
|
||||
- **Evidence**: <N> backend commands, <N> UI screenshots
|
||||
- **Acceptance criteria**: <N>/<M> demonstrated
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
- **Tools not installed**: Show `go install` commands. Do not proceed without them.
|
||||
- **Dev server not running**: Offer to start. If startup fails, produce backend-only demo and note the limitation.
|
||||
- **Authentication failure**: Proceed with backend-only evidence. Note skipped UI screenshots in the document.
|
||||
- **Screenshot failure**: Log the error as a note in the demo document, continue with remaining screenshots.
|
||||
- **No plan found**: Infer from git commits and changed files. Ask the user for a description if commits are ambiguous.
|
||||
- **Rodney/Chrome crash**: Run `rodney stop` then `rodney start` to reset. Retry once. If it fails again, degrade to backend-only.
|
||||
|
||||
## Integration
|
||||
|
||||
- `/build` can suggest running `/demo` after a successful build
|
||||
- `/pr` can invoke `/demo` to generate evidence before or after PR creation
|
||||
- `/plan` produces the acceptance criteria this command verifies visually
|
||||
- Beads (`bd`) can reference demo documents as task completion evidence
|
||||
- Reads plan files from `plans/` directory (same format as `/build`)
|
||||
48
scripts/new-post.sh
Executable file
48
scripts/new-post.sh
Executable file
@ -0,0 +1,48 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
usage() {
|
||||
echo "Usage: $0 \"Post Title\" [blog]"
|
||||
echo " blog: engineering (default) or release-notes"
|
||||
exit 1
|
||||
}
|
||||
|
||||
[[ $# -lt 1 ]] && usage
|
||||
|
||||
title="$1"
|
||||
blog="${2:-engineering}"
|
||||
|
||||
# Title to slug: lowercase, spaces/underscores to hyphens, strip non-alphanumeric
|
||||
slug=$(echo "$title" | tr '[:upper:]' '[:lower:]' | tr ' _' '-' | sed 's/[^a-z0-9-]//g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
|
||||
|
||||
year=$(date +%Y)
|
||||
month_day=$(date +%m-%d)
|
||||
dir="app/priv/blog/${blog}/${year}"
|
||||
file="${dir}/${month_day}-${slug}.md"
|
||||
|
||||
# Find repo root
|
||||
cd "$(dirname "$0")/.."
|
||||
|
||||
mkdir -p "$dir"
|
||||
|
||||
if [[ -f "$file" ]]; then
|
||||
echo "File already exists: $file"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
cat > "$file" <<EOF
|
||||
%{
|
||||
title: "${title}",
|
||||
author: "Firehose Team",
|
||||
tags: ~w(),
|
||||
description: "",
|
||||
published: false
|
||||
}
|
||||
---
|
||||
EOF
|
||||
|
||||
echo "Created: $file"
|
||||
|
||||
if [[ -n "${EDITOR:-}" ]] && [[ -t 1 ]]; then
|
||||
exec "$EDITOR" "$file"
|
||||
fi
|
||||
Loading…
x
Reference in New Issue
Block a user