Skip to content

Integrate showboat demos into agent workflows #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
statik wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Integrate showboat demos into agent workflows #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,3 +55,27 @@ jobs:
with:
name: selftest-results-py${{ matrix.python-version }}
path: selftest-results.xml

verify-demo:
name: Verify showboat demo
if: github.event_name == 'pull_request'
runs-on: ubuntu-latest
Copy link

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since showboat verify executes arbitrary commands from demo.md, this job can hang or run unexpectedly long (intentionally or accidentally). Consider setting a timeout-minutes on the job or the verify step to keep CI usage bounded, especially because this runs on all pull requests that include a demo.

Suggested change
runs-on: ubuntu-latest
runs-on: ubuntu-latest
timeout-minutes: 10

Copilot uses AI. Check for mistakes.
steps:
- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v5
with:
enable-cache: true
- name: Install dependencies
run: uv sync
Copy link

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

uv sync here likely won’t install the tooling that the recommended demo commands run (e.g., just check depends on ruff, which is only in the dev extra per pyproject.toml). If demos follow the AGENTS.md guidance, showboat verify will fail in CI due to missing tools. Consider using uv sync --all-extras (or at least --extra dev) for this job, and consider pinning/choosing a specific Python version (like the selftest matrix) to avoid ubuntu-latest Python drift affecting verification.

Suggested change
run: uv sync
run: uv sync --all-extras --python 3.12

Copilot uses AI. Check for mistakes.
- name: Check for demo
id: check
run: |
if [ -f demo.md ]; then
echo "found=true" >> "$GITHUB_OUTPUT"
else
echo "found=false" >> "$GITHUB_OUTPUT"
echo "No demo.md found — skipping verification"
fi
- name: Verify demo
if: steps.check.outputs.found == 'true'
run: uvx showboat verify demo.md
Comment on lines +79 to +81
Copy link

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The suggested demo flow in AGENTS.md includes running just check, but this job doesn’t install just. Since showboat verify re-runs exec blocks, any demo that follows the documented guidance will fail in CI on the first just invocation. Either add an installation step for just (e.g., via apt) before verification, or update the recommended demo commands to avoid just in CI-verifiable demos.

Copilot uses AI. Check for mistakes.
2 changes: 2 additions & 0 deletions .github/workflows/copilot-setup-steps.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,3 +24,5 @@ jobs:
uses: github/gh-aw/actions/setup-cli@v0.48.1
with:
version: v0.48.1
- name: Install showboat
run: pip install showboat
Comment on lines +27 to +28
Copy link

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This installs showboat via bare pip (and unpinned), which conflicts with the repo guidance to run tooling through uv and makes the setup less reproducible over time. Consider installing uv in this workflow and then installing/pinning showboat via uv tool install/uvx --from (or otherwise pinning the showboat version) so the Copilot Agent environment matches how demos are run in CI (uvx showboat …).

Suggested change
- name: Install showboat
run: pip install showboat
- name: Install uv
run: |
curl -LsSf https://astral.sh/uv/install.sh | sh
- name: Install showboat via uv
run: |
export PATH="$HOME/.local/bin:$PATH"
uv tool install showboat==0.5.0

Copilot uses AI. Check for mistakes.
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# VIP-specific
vip.toml
report/results.json
demo.md
report/_output/
report/_freeze/
report/.quarto/
Expand Down
45 changes: 45 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -191,6 +191,51 @@ silently swallowed inside conditionals.
PR preview to gh-pages via `rossjrw/pr-preview-action@v1`. Uses uv
and Quarto caches.

## Showboat demos

After completing work on a branch, create a showboat demo that proves
your changes work. The demo file is committed to the branch and its
contents are pasted into the PR body under a `## Demo` heading.

### Getting started

Run `uvx showboat --help` at the start of a session to learn the tool.

### Creating a demo

```bash
uvx showboat init demo.md "Feature: <title>"
uvx showboat note demo.md "Explanation of what was done..."
uvx showboat exec demo.md bash "uv run pytest selftests/ -v"
uvx showboat exec demo.md bash "just check"
```

Use `uvx showboat image demo.md <path>` if screenshots are relevant.

### What to demonstrate

- **New tests:** run the new tests and show them passing
- **New features:** exercise the feature with concrete examples
- **Bug fixes:** show the fix in action (before/after if feasible)
- **Refactors:** show that existing tests still pass
- **Always** include `just check` (lint/format) output

### Before committing

```bash
uvx showboat verify demo.md
```

Verification re-runs all `exec` blocks and confirms output matches.
If it fails, fix the demo before committing.

### PR workflow

1. Commit `demo.md` to the branch root
2. Paste the contents of `demo.md` into the PR body under `## Demo`

CI will run `showboat verify demo.md` on PRs that include the file.
Comment on lines +196 to +237
Copy link

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section says demo.md should be committed to the branch root and will be verified in CI, but demo.md is also added to .gitignore in this PR. As written, most contributors won’t be able to git add demo.md without -f, and the CI job will usually skip because the file won’t be present in the checkout. Please reconcile the intended workflow (commit vs. don’t commit) and update these instructions accordingly.

Copilot uses AI. Check for mistakes.

## Common mistakes to avoid

- Forgetting to include `examples/` in ruff check paths.
Expand Down
1 change: 1 addition & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
AGENTS.md
8 changes: 8 additions & 0 deletions justfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,14 @@ report *ARGS:
uv run pytest tests/ --vip-report=report/results.json {{ ARGS }}
cd report && uv run quarto render

# Create a new showboat demo document
demo-init TITLE:
uvx showboat init demo.md "{{ TITLE }}"

# Verify an existing demo document
demo-verify:
uvx showboat verify demo.md

# Generate a Quarto report from selftests (for CI / demo purposes)
report-selftest:
uv run pytest selftests/ --vip-report=report/results.json
Expand Down
Loading