Phase 1 — TMP fixes for templates with UIS services - #25
Merged
Conversation
Cross-team investigation (TMP, UIS, DCT) capturing real-user testing of python-basic-webserver-database. Phased fix plan: ship now (Phase 1), improvements (Phase 2), polish (Phase 3), explicit deferrals (Future). UIS shipped item 1.10 (uis configure --namespace) in PR #121. DCT shipped items 1.8 + 1.9 in v1.7.34 (PR #90). TMP is unblocked to start the README rewrites. Also includes: - INVESTIGATE-github-actions-node24-migration.md (deferred work) - PLAN-p1-tmp-template-docs-fixes.md (this PR's plan) - .gitignore: ignore .claude/ and .devcontainer/backup/ Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Tasks 1.1-1.7 from PLAN-p1-tmp-template-docs-fixes.md (no external dependencies — DCT v1.7.34 and UIS PR #121 are already live for the later phases). Generator fixes: - 1.1: Route install command by template context. UIS stack templates (context: uis) now show `uis template install <id>` instead of the incorrect `dev-template <id>`. Solves A2. - 1.2: Stop emitting the duplicated `## Summary` section. The TemplateHeader description and README intro carry the content. Solves C1. Template hygiene: - 1.3: Add .gitignore to python-basic-webserver-database (excludes .env*, .venv/, Python build artifacts). Solves C6. - 1.4: Add .gitignore to postgresql-demo (sets the standard for stack templates). - 1.5: Add .vscode/settings.json with python-envs.alwaysUseUv: true so VS Code uses uv for package operations on uv-created venvs. Solves B6. Verification (1.6) found a DCT bug to flag in a follow-up: the bulk copy `cp -r .../*` in dev-template.sh does not include hidden directories like .vscode/. The .gitignore is handled explicitly so that part works. Not blocking this PR — we ship the template files; DCT fixes their copy logic separately. Validation (1.7): - validate-metadata.sh: 5 categories, 10 templates valid - validate-docs.sh: 0 errors - npm run build: SUCCESS in devcontainer Plan moved from backlog/ to active/, Phase 1 marked DONE. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Tasks 2.1-2.5 from PLAN-p1-tmp-template-docs-fixes.md. - 2.1: Drop "From the UIS provision-host:" prefix. Commands now work from DCT (via the v1.7.34 shim), host, or UIS context. - 2.2: Populate related: in template-info.yaml with python-basic-webserver-database. The auto-generated "Related Templates" section now appears at the bottom of the page. - 2.3: Add a "Before you start" section explaining the UIS provision-host requirement. - 2.4: Replace manual psql connection example with `uis connect postgresql demo_db` as the primary verify path. - 2.5: Regenerate docs and rebuild — passes. The "Try this with" section now links to python-basic-webserver-database as the consumer-side companion, completing the producer/consumer discovery loop. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…eadme-structure.md updates Phase 3 — python-basic-webserver-database README rewrite around the canonical 7-step workflow: - 3.1: Add "What this is" section with endpoints table - 3.2: Add Prerequisites section (UIS provision-host running check, uis shim mention) - 3.3: Replace Quick Start with the canonical workflow: 1. dev-template python-basic-webserver-database 2. Edit template-info.yaml params 3. (Optional) Customise config/init-database.sql 4. dev-template-configure 5. uis connect postgresql my_cool_app_db (verify the database) 6. uv venv + uv pip install + python app/app.py 7. Open in browser via VS Code Ports tab - 3.4: Embed template-info.yaml content inline - 3.5: Embed config/init-database.sql content inline - 3.6: Drop "Docker Build" and "Kubernetes Deployment" sections, replace with single "Deploy" section using GitHub Actions + ArgoCD - 3.7: Quick Start uses uv (matches B5 + the .vscode/settings.json shipped in 1.5) - 3.8: Validation passes, build SUCCESS Phase 4 — Cross-cutting docs and validation rules: - 4.1+4.2: readme-structure.md documents Prerequisites and "Verify it worked" requirements for templates with requires - 4.3: Drop "Docker Build" and "Kubernetes Deployment" from both validate-rules.conf (no more spurious warnings) and readme-structure.md (no longer in suggested optional sections list). New templates should use a single "Deploy" section instead. - 4.4: readme-structure.md requires inline embedding of template-info.yaml and init file contents for templates with requires - 4.5: Per-template enforcement deferred — would need template-info awareness in validate-docs.sh, tracked as follow-up. Validation results after both phases: - validate-metadata.sh: 5 categories, 10 templates valid - validate-docs.sh: 0 errors, 2 warnings (unrelated plan-based-workflow) - npm run build: SUCCESS Plan status: Completed (pending PR merge). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The .vscode/settings.json shipped in 1.5 risks overwriting the user's existing .vscode/extensions.json (which contains the devcontainer recommendation needed for the project to start) if DCT ever fixes its hidden-directory copy bug. Naive bulk-copy of .vscode/ would clobber project files. Reverted approach: - Remove templates/python-basic-webserver-database/.vscode/settings.json - Document the python-envs.alwaysUseUv setting in the README as a manual one-line addition users can make to their workspace settings if they hit the VS Code "Error refreshing packages" cosmetic error. - Note that they should add it to their existing settings.json, not replace the file. DCT follow-up (tracked in 1.5/1.6 plan notes): - Ideally DCT ships python-envs.alwaysUseUv globally in the base devcontainer image. Then no template needs to ship it. - If DCT wants to support .vscode/ files in templates in the future, they need (a) hidden-directory copy AND (b) JSON-merge for .vscode/*.json files (similar to the .gitignore line-merge they already have). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
terchris
added a commit
that referenced
this pull request
Apr 9, 2026
Phase 1 of PLAN-p1-tmp-template-docs-fixes.md is fully shipped: - All 4 sub-phases complete - PR #25 merged - CI green (generate, build, deploy all passed) - Site deployed The investigation INVESTIGATE-improve-template-docs-with-services.md stays in backlog/ — it has Phase 2 and Phase 3 still pending. Only the TMP Phase 1 portion is done. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
7 tasks
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.
Summary
Ships the TMP-side Phase 1 work from
INVESTIGATE-improve-template-docs-with-services.md. Fixes the bugs real-user testing surfaced inpython-basic-webserver-databaseandpostgresql-demo, plus the cross-cutting MDX generator and template hygiene issues.Cross-team dependencies (both already shipped):
uis configure --namespace --secret-name-prefix+ K8s Secret creationChanges by phase
Phase 1 — Independent TMP fixes (no external deps)
context— postgresql-demo now showsuis template install postgresql-demoinstead ofdev-template postgresql-demo## Summarysection.gitignoreto both templates (excludes.env*,.venv/, Python build artifacts)Phase 2 — postgresql-demo README rewrite
related: [python-basic-webserver-database]so the auto-generated "Related Templates" section appearspsqlconnection example withuis connect postgresql demo_dbPhase 3 — python-basic-webserver-database README rewrite
/,/tasks,/health)dev-template python-basic-webserver-databasetemplate-info.yamlparamsconfig/init-database.sqldev-template-configureuis connect postgresql my_cool_app_db(verify the database)uv venv && uv pip install -r requirements.txt && python app/app.pytemplate-info.yamlandconfig/init-database.sqlcontent inline so users see what they're editinguv(notpip) — DCT ships uvPhase 4 — Cross-cutting docs
readme-structure.mddocuments the new conventions for templates withrequiresvalidate-rules.confno longer warns on those headings — new templates should use a single "Deploy" section insteadWhat's NOT in this PR (intentionally)
.vscode/settings.jsonforpython-envs.alwaysUseUv— initially shipped, then reverted to avoid risk of overwriting users' existing.vscode/extensions.json(which contains the devcontainer recommendation needed for the project to start). The setting is documented in the README as a manual one-line addition users can make if they hit the cosmetic VS Code warning.Follow-ups for DCT (not blocking this PR)
Two findings during 1.6 verification:
cp -r "$TEMPLATE_PATH/"* "$CALLER_DIR/"indev-template.shdoesn't include hidden directories like.vscode/. The.gitignoreis handled explicitly so that part works..vscode/: if DCT ever wants to support.vscode/files in templates, they need (a) hidden-directory copy AND (b) JSON-merge for.vscode/*.jsonfiles (like they already have for.gitignore's line-merge).python-envs.alwaysUseUvglobally: ideally as a base devcontainer setting. Then no template needs to ship it.Test plan
bash scripts/validate-metadata.sh— 5 categories, 10 templates validbash scripts/validate-docs.sh— 0 errors, 2 warnings (unrelatedplan-based-workflowREADME)bash scripts/generate-docs-markdown.sh --force— generates 10 template detail pagesnpm run build --prefix website— passes inside the devcontainerinstall="uis template install postgresql-demo"## Summarysection emitted by generator for any template🤖 Generated with Claude Code