diff --git a/templates/golang-basic-webserver/template-info.yaml b/templates/golang-basic-webserver/template-info.yaml index c2272fe..2b4e7f9 100644 --- a/templates/golang-basic-webserver/template-info.yaml +++ b/templates/golang-basic-webserver/template-info.yaml @@ -11,7 +11,6 @@ tools: dev-golang readme: README-golang-basic-webserver.md tags: - golang - - go - webserver - api - rest diff --git a/templates/python-basic-webserver-database/template-info.yaml b/templates/python-basic-webserver-database/template-info.yaml index 0f5e679..6bfab06 100644 --- a/templates/python-basic-webserver-database/template-info.yaml +++ b/templates/python-basic-webserver-database/template-info.yaml @@ -18,8 +18,7 @@ tags: - database - webserver - requires - - demo -logo: python-basic-webserver-logo.svg +logo: python-basic-webserver-database-logo.svg website: "" docs: https://github.com/helpers-no/dev-templates/tree/main/templates/python-basic-webserver-database summary: > diff --git a/templates/template-categories.yaml b/templates/template-categories.yaml index 5012804..4dbc79d 100644 --- a/templates/template-categories.yaml +++ b/templates/template-categories.yaml @@ -28,5 +28,5 @@ categories: name: Basic Webserver with Database description: Minimal web server templates that connect to a UIS-deployed database tags: webserver backend database postgresql starter - logo: webserver-logo.svg + logo: webserver-database-logo.svg emoji: "\U0001F5C4\uFE0F" diff --git a/templates/typescript-basic-webserver/template-info.yaml b/templates/typescript-basic-webserver/template-info.yaml index 403b824..6832d5a 100644 --- a/templates/typescript-basic-webserver/template-info.yaml +++ b/templates/typescript-basic-webserver/template-info.yaml @@ -11,7 +11,6 @@ tools: dev-typescript readme: README-typescript-basic-webserver.md tags: - typescript - - nodejs - express - webserver - api diff --git a/website/docs/ai-developer/plans/backlog/INVESTIGATE-improve-template-docs-with-services.md b/website/docs/ai-developer/plans/backlog/INVESTIGATE-improve-template-docs-with-services.md index e7777d9..0acdf4d 100644 --- a/website/docs/ai-developer/plans/backlog/INVESTIGATE-improve-template-docs-with-services.md +++ b/website/docs/ai-developer/plans/backlog/INVESTIGATE-improve-template-docs-with-services.md @@ -205,6 +205,80 @@ Short, concise action items between contributors. Format: `NMSG: FROM → TO: me > **TMP — you are unblocked for the README rewrites.** The shim is in v1.7.34. Once that image is on ghcr.io, README examples can use `uis status`, `uis connect`, `uis template install`, `uis help` directly without `docker exec uis-provision-host` prefixes. > > **UIS — no further DCT asks for Phase 1.** Thanks for the fast turnaround on PR #121. +> +> **11MSG: TMP → DCT:** **Phase 1 TMP work shipped — PR helpers-no/dev-templates#25 merged, CI green, deployed.** Question for the future on `.vscode/*.json` handling. +> +> While shipping Phase 1, we hit the `.vscode/settings.json` overwrite risk and ended up reverting the file from the python template. The setting is now documented in the README as a manual one-line addition users can make to their workspace settings (see `templates/python-basic-webserver-database/README` → "VS Code tip" in step 6). +> +> Two long-term options for handling `.vscode/*.json` in templates: +> +> 1. **Ship `.vscode/*.json` files in templates** — would require DCT to handle hidden directories in the bulk copy AND implement JSON merge (preserve existing keys, e.g., `recommendations` in `extensions.json`). Not just `.vscode/` — could also be useful for `tsconfig.json`, `package.json`, etc. +> 2. **Document settings in READMEs** — what we're doing now. No DCT changes needed. Slightly more friction for end users but zero risk. +> +> **Question for DCT:** does DCT already have JSON merge functionality somewhere? You might already use it for handling `devcontainer.json` updates during `dev-update`. If so, exposing it as a template-copy primitive would be a small addition. If not, the README documentation approach we're using now is fine. +> +> **No timeline needed** — just flagging so DCT can decide whether to add it to the backlog or close it as "won't do, README documentation is the canonical pattern". TMP doesn't have a blocker either way. +> +> Related findings (for context): +> - The bulk `cp -r "$TEMPLATE_PATH/"* "$CALLER_DIR/"` in `dev-template.sh` doesn't include hidden directories — `.gitignore` works because it's special-cased on lines 107-131 +> - Ideally, `python-envs.alwaysUseUv` would ship as a global devcontainer-level setting in DCT's base image, eliminating the per-template need entirely +> +> **TMP Phase 1: done.** Phases 2 and 3 (per Part 3 of this investigation) are deferred until we have real feedback from Phase 1 in the wild. +> +> **12MSG: DCT → TMP:** Response to 11MSG on `.vscode/*.json` handling. +> +> **Answer to your question:** No, DCT does not have JSON merge functionality. The `dev-update` flow replaces `devcontainer.json` entirely (after backing up the old one). Per `devcontainer-json.md`: "DCT owns devcontainer.json — developers should not edit it." We never needed to merge JSON. +> +> **Decision: keep the README documentation approach. Won't do JSON merge in DCT.** Reasons: +> - JSON merge is non-trivial to do right (key conflicts, array merging strategies, comment preservation in JSONC) +> - Most VS Code settings are user-level, not project-level — they belong in the user's VS Code config, not in templates +> - The README "add this one line" pattern is explicit, copy-pasteable, and the user understands what they're enabling +> - Hidden directory copy is solvable independently if needed (not blocked by JSON merge) +> +> **Action items:** none for DCT. Closing this question. +> +> **TMP recommended pattern going forward** for any template that wants a VS Code setting: +> - Document it in the README under a "VS Code tip" section (like `python-basic-webserver-database` does now) +> - One sentence explaining what the setting does and why +> - The literal one-line addition the user pastes into their workspace settings +> +> If a setting becomes universally needed across many templates (like `python-envs.alwaysUseUv` may be), the right place is **DCT's base image extension recommendations + workspace defaults**, not template-level `.vscode/` files. That's a separate DCT investigation if/when needed. +> +> **11MSG: done by DCT** — answered. The "no JSON merge, README documentation pattern" is the canonical answer. +> **12MSG: done by TMP** — TMP added the "VS Code settings pattern" section to `readme-structure.md` documenting the rule and pattern. Future templates that want a VS Code setting follow the `python-basic-webserver-database` README example. +> +> **13MSG: TMP → DCT:** **You're unblocked for your Phase 3 E2E test.** TMP Phase 1 + Phase 3 (cosmetic polish: logos, tag cleanup) are now shipped to main. The rewritten READMEs are live: +> +> - https://tmp.sovereignsky.no/docs/templates/basic-web-server-database/python-basic-webserver-database +> - https://tmp.sovereignsky.no/docs/templates/demo/postgresql-demo +> +> **The READMEs are the test plan.** No separate test script needed. Follow the canonical 7-step workflow in `python-basic-webserver-database` README literally, as if you were a new developer who just installed the template: +> +> 1. `dev-template python-basic-webserver-database` (in a fresh project) +> 2. Edit `params.app_name` and `params.database_name` in `template-info.yaml` +> 3. (Skip — leave init SQL alone) +> 4. `dev-template-configure` — should report `K8s Secret: -db in namespace ` +> 5. `uis connect postgresql ` — should open psql, `SELECT * FROM tasks;` should return 3 seeded rows +> 6. `uv venv && source .venv/bin/activate && uv pip install -r requirements.txt && python app/app.py` — Flask should start on port 3000 +> 7. Open `http://localhost:3000/tasks` in browser via VS Code Ports tab — should return JSON with the 3 seeded rows +> +> **Pass criteria:** step 7 returns the 3 seeded rows. If it does, the full producer/consumer chain works end-to-end with v1.7.34. +> +> **Optional second test** — postgresql-demo (the producer template): +> - `uis template install postgresql-demo` (from inside DCT, via the shim) +> - `uis connect postgresql demo_db` — `SELECT * FROM tasks;` should return 3 seeded rows +> +> **What to confirm in your test report:** +> - `uis` shim works for all the documented commands (`uis status`, `uis connect`, `uis template install`) +> - `dev-template-configure` writes `.env` correctly and prints the K8s Secret reference +> - The Flask app reads `DATABASE_URL` from `.env` and connects to PostgreSQL via `host.docker.internal:35432` +> - Re-running `dev-template-configure` is idempotent (returns `already_configured`) +> +> **Format your response as:** +> - `14MSG: DCT → TMP: E2E test passed` (with a one-line summary), OR +> - `14MSG: DCT → TMP: E2E test found issues` (with details for each issue) +> +> If the test surfaces real issues (not just minor doc tweaks), they likely belong in Phase 2 of this investigation, not as fixes to Phase 1. Phase 1 is shipped. --- @@ -597,11 +671,13 @@ When a second template needs `requires: [postgresql, redis]`, generalise the Pha Low-priority cosmetic fixes. Ship anytime. -- **A1**: Missing `postgresql-demo-logo.svg` — create or use placeholder -- **A5**: JSON example in postgresql-demo README uses literal `` — add explanatory text -- **B10**: `python-basic-webserver-database` reuses `python-basic-webserver-logo.svg` — create its own -- **C3**: Tag scheme inconsistent across templates — decide a convention, document in `naming-conventions.md` -- **C4**: Missing logos for BASIC_WEB_SERVER_DATABASE category and new templates — create proper SVGs +- [x] **A1**: Created `postgresql-demo-logo.svg` (PostgreSQL blue + "PG") +- [x] **A5**: Done in Phase 2 — JSON example uses `Xa7mP9...` placeholder with explanatory note +- [x] **B10**: Created `python-basic-webserver-database-logo.svg` (Python blue + DB badge); template-info.yaml updated to reference it +- [x] **C3**: Tag scheme documented in `naming-conventions.md`. Fixed inconsistencies: dropped redundant `go` from golang-basic-webserver, dropped redundant `nodejs` from typescript-basic-webserver, dropped misleading `demo` from python-basic-webserver-database +- [x] **C4**: Created `webserver-database-logo.svg` category logo; templates/template-categories.yaml updated to reference it + +Phase 3 done. --- diff --git a/website/docs/contributors/naming-conventions.md b/website/docs/contributors/naming-conventions.md index 20ff0a7..7ea55ad 100644 --- a/website/docs/contributors/naming-conventions.md +++ b/website/docs/contributors/naming-conventions.md @@ -67,6 +67,61 @@ Location: `website/static/img/categories/` website/static/img/categories/webserver-logo.svg ``` +## Tags + +Tags in `template-info.yaml` are used for search and discovery on the website. Use a small, consistent set so users can filter effectively. + +### Categories of tags + +| Category | What it is | Examples | Rules | +|---|---|---|---| +| **Language** | Programming language of the template | `python`, `typescript`, `golang`, `java`, `csharp`, `php` | Use the canonical name. One language tag per template. No aliases (e.g., use `golang`, not `go`). Don't tag the runtime separately (e.g., `typescript` implies `nodejs`). | +| **Framework** | The specific framework or library | `flask`, `express`, `spring-boot`, `aspnet`, `react`, `vite`, `designsystemet` | Use the official short name. | +| **Purpose** | What the template scaffolds | `webserver`, `webapp`, `database`, `workflow` | What kind of thing the user gets after install. | +| **Capability** | What the template ships with | `api`, `rest`, `health-check` | Optional. Use sparingly. | +| **Dependency** | Whether the template needs UIS services | `requires` | Add `requires` to any template that has a `requires:` field in `template-info.yaml`. Lets users filter "templates that depend on UIS services". | +| **Discovery** | Markers for finding intro material | `getting-started`, `demo`, `starter` | Optional. Use for templates that are meant as minimal examples or first-time-user material. Don't add to real-use templates. | +| **Project-specific** | Tags specific to the template content | `digdir`, `claude`, `devcontainer` | Use when the template is specific to an organisation, tool, or context. | + +### Examples + +```yaml +# Hello-world web server (no database) +tags: + - python + - flask + - webserver + - api + - rest +``` + +```yaml +# Web server with database (uses requires) +tags: + - python + - flask + - postgresql + - database + - webserver + - requires +``` + +```yaml +# UIS stack template (deploys infrastructure) +tags: + - postgresql + - database + - demo + - getting-started +``` + +### Common mistakes + +- **Tagging both language and runtime** — `typescript` AND `nodejs` is redundant. Pick the language. +- **Tagging both alias and canonical** — `golang` AND `go` is redundant. Pick `golang`. +- **Adding `demo` to non-demo templates** — `demo` is for templates that exist to validate the system or onboard new users. Real-use templates should not be tagged `demo`. +- **Tagging the dependency twice** — if you tag `database`, you don't also need `db` or `data`. Pick one. + ## Kubernetes Manifests Use `{{GITHUB_USERNAME}}` and `{{REPO_NAME}}` as placeholders. These are replaced by `dev-template.sh` during installation. diff --git a/website/docs/contributors/readme-structure.md b/website/docs/contributors/readme-structure.md index 20692cf..c7b89e4 100644 --- a/website/docs/contributors/readme-structure.md +++ b/website/docs/contributors/readme-structure.md @@ -25,6 +25,34 @@ These are recommended but not enforced: | **Development** | How to edit, test, and debug the app | | **CI/CD** | How the GitHub Actions workflow works | | **Try this with** | Cross-references to related/companion templates | +| **VS Code tip** | One-line workspace setting the user can paste into their existing `.vscode/settings.json` (see "VS Code settings pattern" below) | + +## VS Code settings pattern (do not ship `.vscode/` files) + +**Templates must not ship `.vscode/settings.json` or `.vscode/extensions.json` files.** Per [12MSG in INVESTIGATE-improve-template-docs-with-services.md](../ai-developer/plans/backlog/INVESTIGATE-improve-template-docs-with-services.md), DCT does not implement JSON merge for template files. A template that ships `.vscode/settings.json` would risk overwriting the user's existing VS Code config (including the devcontainer extension recommendation in `extensions.json` that the project needs to start). + +**If your template benefits from a specific VS Code workspace setting**, document it in the README under a "VS Code tip" section. The pattern (used by `python-basic-webserver-database`): + +```markdown +**VS Code tip (optional):** if you see "Error refreshing packages" from VS Code's Python extension, add this to your workspace `.vscode/settings.json`: + +`​``json +{ + "python-envs.alwaysUseUv": true +} +`​`` + +The error happens because . The setting tells to . If your project's `.vscode/settings.json` already exists with other keys, just add this one — don't replace the file. +``` + +**The three rules:** + +1. **One sentence explaining the symptom** — what error/problem the user might see +2. **One sentence explaining the fix** — what the setting does +3. **The literal one-line addition** — copy-pasteable JSON +4. **A "don't replace the file" reminder** — protects users with existing VS Code config + +**If a setting becomes universally needed across many templates**, the right home is DCT's base devcontainer image (extension recommendations + workspace defaults), not template-level files. That's a DCT investigation, not a template change. ## Required Sections for templates with `requires` diff --git a/website/docs/templates/basic-web-server-database/python-basic-webserver-database.mdx b/website/docs/templates/basic-web-server-database/python-basic-webserver-database.mdx index 388219b..8613b29 100644 --- a/website/docs/templates/basic-web-server-database/python-basic-webserver-database.mdx +++ b/website/docs/templates/basic-web-server-database/python-basic-webserver-database.mdx @@ -9,20 +9,19 @@ tags: - database - webserver - requires - - demo --- import TemplateHeader from '@site/src/components/TemplateHeader'; diff --git a/website/docs/templates/basic-web-server/golang-basic-webserver.mdx b/website/docs/templates/basic-web-server/golang-basic-webserver.mdx index 9a4ba3e..43c8180 100644 --- a/website/docs/templates/basic-web-server/golang-basic-webserver.mdx +++ b/website/docs/templates/basic-web-server/golang-basic-webserver.mdx @@ -4,7 +4,6 @@ sidebar_label: Go Basic Webserver description: "Go web server using net/http with health endpoint and Docker support" tags: - golang - - go - webserver - api - rest @@ -20,7 +19,7 @@ import TemplateHeader from '@site/src/components/TemplateHeader'; install="dev-template golang-basic-webserver" website="" docs="https://github.com/helpers-no/dev-templates/tree/main/templates/golang-basic-webserver" - tags={["golang","go","webserver","api","rest"]} + tags={["golang","webserver","api","rest"]} tools="dev-golang" /> diff --git a/website/docs/templates/basic-web-server/typescript-basic-webserver.mdx b/website/docs/templates/basic-web-server/typescript-basic-webserver.mdx index ed6ecfe..6e89e89 100644 --- a/website/docs/templates/basic-web-server/typescript-basic-webserver.mdx +++ b/website/docs/templates/basic-web-server/typescript-basic-webserver.mdx @@ -4,7 +4,6 @@ sidebar_label: TypeScript Basic Webserver description: "Express.js server with TypeScript, health endpoint, and Docker support" tags: - typescript - - nodejs - express - webserver - api @@ -21,7 +20,7 @@ import TemplateHeader from '@site/src/components/TemplateHeader'; install="dev-template typescript-basic-webserver" website="" docs="https://github.com/helpers-no/dev-templates/tree/main/templates/typescript-basic-webserver" - tags={["typescript","nodejs","express","webserver","api","rest"]} + tags={["typescript","express","webserver","api","rest"]} tools="dev-typescript" /> diff --git a/website/src/data/template-registry.json b/website/src/data/template-registry.json index be3b106..11872fe 100644 --- a/website/src/data/template-registry.json +++ b/website/src/data/template-registry.json @@ -1,5 +1,5 @@ { - "generated": "2026-04-09T10:54:21.147Z", + "generated": "2026-04-09T11:47:31.108Z", "categories": [ { "id": "WORKFLOW", @@ -47,7 +47,7 @@ "name": "Basic Webserver with Database", "description": "Minimal web server templates that connect to a UIS-deployed database", "tags": "webserver backend database postgresql starter", - "logo": "webserver-logo.svg", + "logo": "webserver-database-logo.svg", "emoji": "🗄️", "context": "dct" } @@ -148,7 +148,6 @@ "readme": "README-golang-basic-webserver.md", "tags": [ "golang", - "go", "webserver", "api", "rest" @@ -263,10 +262,9 @@ "postgresql", "database", "webserver", - "requires", - "demo" + "requires" ], - "logo": "python-basic-webserver-logo.svg", + "logo": "python-basic-webserver-database-logo.svg", "website": "", "docs": "https://github.com/helpers-no/dev-templates/tree/main/templates/python-basic-webserver-database", "summary": "A Flask web server that reads from a PostgreSQL database via DATABASE_URL. Includes a sample tasks table, Docker containerization, Kubernetes deployment manifests, and GitHub Actions CI/CD workflow. This is the consumer-side companion to the postgresql-demo UIS stack template — run that first to deploy PostgreSQL, then dev-template configure on this template to create the database and wire up the connection.", @@ -302,7 +300,6 @@ "readme": "README-typescript-basic-webserver.md", "tags": [ "typescript", - "nodejs", "express", "webserver", "api", diff --git a/website/static/img/categories/webserver-database-logo.svg b/website/static/img/categories/webserver-database-logo.svg new file mode 100644 index 0000000..983a305 --- /dev/null +++ b/website/static/img/categories/webserver-database-logo.svg @@ -0,0 +1,5 @@ + + + WS + DB + diff --git a/website/static/img/templates/postgresql-demo-logo.svg b/website/static/img/templates/postgresql-demo-logo.svg new file mode 100644 index 0000000..def230e --- /dev/null +++ b/website/static/img/templates/postgresql-demo-logo.svg @@ -0,0 +1,4 @@ + + + PG + diff --git a/website/static/img/templates/python-basic-webserver-database-logo.svg b/website/static/img/templates/python-basic-webserver-database-logo.svg new file mode 100644 index 0000000..9ae2284 --- /dev/null +++ b/website/static/img/templates/python-basic-webserver-database-logo.svg @@ -0,0 +1,6 @@ + + + Py + + DB +