From dee1547471da6aab2dabfdbcae412833f8db849d Mon Sep 17 00:00:00 2001 From: James Cox-Morton Date: Thu, 13 Aug 2026 09:59:13 +0100 Subject: [PATCH 1/3] Authoring best practices --- .../05-authoring-best-practices.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 docs/project-specification/05-authoring-best-practices.md diff --git a/docs/project-specification/05-authoring-best-practices.md b/docs/project-specification/05-authoring-best-practices.md new file mode 100644 index 00000000..73fc767c --- /dev/null +++ b/docs/project-specification/05-authoring-best-practices.md @@ -0,0 +1,19 @@ +# Topo Project Authoring Best Practices + +Recommendations for delivering the best and most consistent user experience with Topo Projects + +## Be semantically correct and leverage `x-topo` attributes as appropriate + +`x-topo` contains attributes that help users discover and use your Project. Ensure you have considered all available attributes in the schema and used them as appropriate. + +The [Topo project-authoring skills](https://github.com/arm/topo#project-authoring-skills) can help you lint and improve your Project. + +## Only require `topo deploy` to build and run + +Running `topo deploy` should be sufficient to build and start the application. Define every required build, dependency-fetching, and setup step in `compose.yaml` or its Dockerfiles, or provide the result in a referenced container image. Do not require users to run additional commands manually. + +[Multi-stage builds](https://docs.docker.com/build/building/multi-stage/) can be used for compilation, dependency fetching, code generation, and asset bundling. Copy only the resulting artifacts and runtime dependencies into the final stage. This ensures `topo deploy` performs the complete build while keeping build tools, caches, and other build-only files out of the runtime image. + +### Be fast to build and iterate + +The best Topo Projects are fast to build, deploy, and iterate on. See [Build Optimization](https://github.com/arm/topo/blob/main/docs/project-specification/04-build-optimization.md) or use the [`topo-project-optimize-deployment` skill](https://github.com/arm/topo#project-authoring-skills) for guidance on specific performance best practices. From fa6396ea8f1fb46534e36faf18e3d387204ab600 Mon Sep 17 00:00:00 2001 From: James Cox-Morton Date: Thu, 13 Aug 2026 11:26:33 +0100 Subject: [PATCH 2/3] Update surrounding docs in light of new best practices --- .../05-authoring-best-practices.md | 2 +- docs/project-specification/README.md | 9 ++++++--- skills/_shared/topo-project-context.md | 5 ++++- .../references/topo-project-context.md | 5 ++++- .../references/topo-project-context.md | 5 ++++- skills/topo-project-lint/SKILL.md | 15 ++++++++++++--- .../references/topo-project-context.md | 5 ++++- .../references/topo-project-context.md | 5 ++++- 8 files changed, 39 insertions(+), 12 deletions(-) diff --git a/docs/project-specification/05-authoring-best-practices.md b/docs/project-specification/05-authoring-best-practices.md index 73fc767c..a8ce9458 100644 --- a/docs/project-specification/05-authoring-best-practices.md +++ b/docs/project-specification/05-authoring-best-practices.md @@ -16,4 +16,4 @@ Running `topo deploy` should be sufficient to build and start the application. D ### Be fast to build and iterate -The best Topo Projects are fast to build, deploy, and iterate on. See [Build Optimization](https://github.com/arm/topo/blob/main/docs/project-specification/04-build-optimization.md) or use the [`topo-project-optimize-deployment` skill](https://github.com/arm/topo#project-authoring-skills) for guidance on specific performance best practices. +The best Topo Projects are fast to build, deploy, and iterate on. See [Build Optimization](04-build-optimization.md) or use the [`topo-project-optimize-deployment` skill](https://github.com/arm/topo#project-authoring-skills) for guidance on specific performance best practices. diff --git a/docs/project-specification/README.md b/docs/project-specification/README.md index 330dfe01..16ef1d39 100644 --- a/docs/project-specification/README.md +++ b/docs/project-specification/README.md @@ -42,6 +42,8 @@ Because this is valid Compose, any Project can be run with plain `docker compose - [Authoring Topo Projects](01-authoring-projects.md) - [Project Configuration](02-project-configuration.md) - [Schema Compliance](03-schema.md) + - [Build Optimization](04-build-optimization.md) + - [Authoring Best Practices](05-authoring-best-practices.md) - Machine-readable schema: - [`schema/topo-project-specification.json`](https://github.com/arm/topo/blob/main/docs/project-specification/schema/topo-project-specification.json) @@ -58,9 +60,10 @@ We welcome any contributors who wish to add their own Project to the project cat If you want your Project to be added to the project catalog: -1. Review the [Authoring Topo Projects section of the Specification](01-authoring-projects.md). -2. [Validate Schema Compliance](#validate-schema-compliance) of your proposed Project. -3. Open a Pull Request in the `Topo Project Catalog` repository to update the [catalog sources](https://github.com/arm/topo-project-catalog/blob/main/data/github_sources.json). +1. Review the [Authoring Best Practices](05-authoring-best-practices.md). +2. Review the catalog's [Project Acceptance Criteria](https://github.com/arm/topo-project-catalog/blob/main/docs/project-acceptance-criteria.md). +3. [Validate Schema Compliance](#validate-schema-compliance) of your proposed Project. +4. Open a Pull Request in the `Topo Project Catalog` repository to update the [catalog sources](https://github.com/arm/topo-project-catalog/blob/main/data/github_sources.json). ### Validate Schema Compliance diff --git a/skills/_shared/topo-project-context.md b/skills/_shared/topo-project-context.md index 02937133..6b19049c 100644 --- a/skills/_shared/topo-project-context.md +++ b/skills/_shared/topo-project-context.md @@ -15,10 +15,13 @@ Use Topo vocabulary precisely: Refresh spec-sensitive context at runtime before making or validating Project changes. Authoritative references, in order: - Published Topo Project Specification schema: `https://raw.githubusercontent.com/arm/topo/refs/heads/main/docs/project-specification/schema/topo-project-specification.json`. -- Published Topo Project Specification docs: `https://github.com/arm/topo/tree/main/docs/project-specification`, especially `README.md`, `01-authoring-projects.md`, `02-project-configuration.md`, and `03-schema.md`. +- Published Topo Project Specification docs: `https://github.com/arm/topo/tree/main/docs/project-specification`, especially `README.md`, `01-authoring-projects.md`, `02-project-configuration.md`, `03-schema.md`, and `05-authoring-best-practices.md`. +- Topo Project Catalog acceptance policy: `https://github.com/arm/topo-project-catalog/blob/main/docs/project-acceptance-criteria.md`. - Published Topo glossary for domain terms: `https://github.com/arm/topo/blob/main/docs/introduction/glossary.md`. - Compose Spec for standard Compose semantics. Do not invent non-standard Compose keys except the root-level `x-topo` extension. When references conflict, prefer the schema for validation behavior, then the specification docs for authoring intent, then the target repository's actual Compose behavior for the smallest safe change. +Keep specification requirements, authoring best practices, and catalog policy distinct. The schema and specification define whether a Project is valid. The authoring best practices provide technical guidance for making Projects accurate, reproducible, adaptable, tested, and fast to iterate. The catalog applies additional curation and acceptance policy. Only apply catalog policy when the user asks about catalog inclusion, submission, acceptance, or readiness. + When validating changes, check if `topo` is installed, and prompt the user for an SSH target to test against. `topo clone dir:./path/to/project` can be used to test project parameters, `topo deploy` can be used to test build and deploy. diff --git a/skills/topo-project-bootstrap/references/topo-project-context.md b/skills/topo-project-bootstrap/references/topo-project-context.md index 02937133..6b19049c 100644 --- a/skills/topo-project-bootstrap/references/topo-project-context.md +++ b/skills/topo-project-bootstrap/references/topo-project-context.md @@ -15,10 +15,13 @@ Use Topo vocabulary precisely: Refresh spec-sensitive context at runtime before making or validating Project changes. Authoritative references, in order: - Published Topo Project Specification schema: `https://raw.githubusercontent.com/arm/topo/refs/heads/main/docs/project-specification/schema/topo-project-specification.json`. -- Published Topo Project Specification docs: `https://github.com/arm/topo/tree/main/docs/project-specification`, especially `README.md`, `01-authoring-projects.md`, `02-project-configuration.md`, and `03-schema.md`. +- Published Topo Project Specification docs: `https://github.com/arm/topo/tree/main/docs/project-specification`, especially `README.md`, `01-authoring-projects.md`, `02-project-configuration.md`, `03-schema.md`, and `05-authoring-best-practices.md`. +- Topo Project Catalog acceptance policy: `https://github.com/arm/topo-project-catalog/blob/main/docs/project-acceptance-criteria.md`. - Published Topo glossary for domain terms: `https://github.com/arm/topo/blob/main/docs/introduction/glossary.md`. - Compose Spec for standard Compose semantics. Do not invent non-standard Compose keys except the root-level `x-topo` extension. When references conflict, prefer the schema for validation behavior, then the specification docs for authoring intent, then the target repository's actual Compose behavior for the smallest safe change. +Keep specification requirements, authoring best practices, and catalog policy distinct. The schema and specification define whether a Project is valid. The authoring best practices provide technical guidance for making Projects accurate, reproducible, adaptable, tested, and fast to iterate. The catalog applies additional curation and acceptance policy. Only apply catalog policy when the user asks about catalog inclusion, submission, acceptance, or readiness. + When validating changes, check if `topo` is installed, and prompt the user for an SSH target to test against. `topo clone dir:./path/to/project` can be used to test project parameters, `topo deploy` can be used to test build and deploy. diff --git a/skills/topo-project-context/references/topo-project-context.md b/skills/topo-project-context/references/topo-project-context.md index 02937133..6b19049c 100644 --- a/skills/topo-project-context/references/topo-project-context.md +++ b/skills/topo-project-context/references/topo-project-context.md @@ -15,10 +15,13 @@ Use Topo vocabulary precisely: Refresh spec-sensitive context at runtime before making or validating Project changes. Authoritative references, in order: - Published Topo Project Specification schema: `https://raw.githubusercontent.com/arm/topo/refs/heads/main/docs/project-specification/schema/topo-project-specification.json`. -- Published Topo Project Specification docs: `https://github.com/arm/topo/tree/main/docs/project-specification`, especially `README.md`, `01-authoring-projects.md`, `02-project-configuration.md`, and `03-schema.md`. +- Published Topo Project Specification docs: `https://github.com/arm/topo/tree/main/docs/project-specification`, especially `README.md`, `01-authoring-projects.md`, `02-project-configuration.md`, `03-schema.md`, and `05-authoring-best-practices.md`. +- Topo Project Catalog acceptance policy: `https://github.com/arm/topo-project-catalog/blob/main/docs/project-acceptance-criteria.md`. - Published Topo glossary for domain terms: `https://github.com/arm/topo/blob/main/docs/introduction/glossary.md`. - Compose Spec for standard Compose semantics. Do not invent non-standard Compose keys except the root-level `x-topo` extension. When references conflict, prefer the schema for validation behavior, then the specification docs for authoring intent, then the target repository's actual Compose behavior for the smallest safe change. +Keep specification requirements, authoring best practices, and catalog policy distinct. The schema and specification define whether a Project is valid. The authoring best practices provide technical guidance for making Projects accurate, reproducible, adaptable, tested, and fast to iterate. The catalog applies additional curation and acceptance policy. Only apply catalog policy when the user asks about catalog inclusion, submission, acceptance, or readiness. + When validating changes, check if `topo` is installed, and prompt the user for an SSH target to test against. `topo clone dir:./path/to/project` can be used to test project parameters, `topo deploy` can be used to test build and deploy. diff --git a/skills/topo-project-lint/SKILL.md b/skills/topo-project-lint/SKILL.md index 73799dd8..e35c2a67 100644 --- a/skills/topo-project-lint/SKILL.md +++ b/skills/topo-project-lint/SKILL.md @@ -1,11 +1,11 @@ --- name: topo-project-lint -description: Check Topo Project metadata correctness. Use when validating compose.yaml x-topo metadata, README alignment, deployment success messages, or project parameter wiring. +description: Check Topo Project correctness and catalog readiness. Use when validating compose.yaml x-topo metadata, README alignment, deployment success messages, project parameter wiring, or catalog acceptance criteria. --- # Topo Project Lint -Use this skill when the user asks to lint, validate, check, review, or fix Topo Project metadata correctness. +Use this skill when the user asks to lint, validate, check, review, or fix Topo Project metadata correctness or catalog readiness. Before acting, read `references/topo-project-context.md` for shared Topo Project vocabulary, authoritative references, and validation expectations. @@ -18,6 +18,7 @@ Run these checks in order. If the user asked you to fix issues, make the smalles 3. Check that `x-topo.name` and `x-topo.description` match `README.md`. 4. Check that `x-topo.deployment_success_message` exists and is useful. 5. Check that every `x-topo.parameters` entry is consumed by the corresponding Docker build. +6. If catalog readiness was requested, assess the Project against the catalog's current Project Acceptance Criteria. ## Checks @@ -61,6 +62,14 @@ Run these checks in order. If the user asked you to fix issues, make the smalles - Flag `services..build.args` entries that look user-configurable but are missing from `x-topo.parameters` when the user asked for a comprehensive lint. - Do not require runtime-only environment variables to appear in `x-topo.parameters`; this check is only for Docker build arguments. +### 6. Catalog Readiness + +- Run this check only when the user asks about catalog inclusion, acceptance, submission, or readiness. +- Read the current catalog acceptance policy from `https://github.com/arm/topo-project-catalog/blob/main/docs/project-acceptance-criteria.md` before assessing the Project. Do not substitute Topo's authoring best practices for catalog policy. +- Apply the technical guidance from Topo's authoring best practices first, then assess the additional selection and quality thresholds defined by the catalog. +- Distinguish repository evidence from checks that were actually run. Do not infer reliability, target compatibility, or performance from metadata alone. +- Treat schema failures, inaccurate compatibility declarations, and required manual pre-deployment steps as blocking. Report subjective acceptance decisions and tests requiring unavailable target hardware as needing maintainer or hardware validation. + ## Reporting -Report findings in the same order as the checks. Include file paths, line numbers when available, the validation command used, and whether each check passed or failed. If changes were made, summarize the files edited and the re-validation result. +Report findings in the same order as the checks. Include file paths, line numbers when available, the validation command used, and whether each check passed or failed. For catalog-readiness reviews, separate confirmed evidence, blocking issues, and unverified criteria. If changes were made, summarize the files edited and the re-validation result. diff --git a/skills/topo-project-lint/references/topo-project-context.md b/skills/topo-project-lint/references/topo-project-context.md index 02937133..6b19049c 100644 --- a/skills/topo-project-lint/references/topo-project-context.md +++ b/skills/topo-project-lint/references/topo-project-context.md @@ -15,10 +15,13 @@ Use Topo vocabulary precisely: Refresh spec-sensitive context at runtime before making or validating Project changes. Authoritative references, in order: - Published Topo Project Specification schema: `https://raw.githubusercontent.com/arm/topo/refs/heads/main/docs/project-specification/schema/topo-project-specification.json`. -- Published Topo Project Specification docs: `https://github.com/arm/topo/tree/main/docs/project-specification`, especially `README.md`, `01-authoring-projects.md`, `02-project-configuration.md`, and `03-schema.md`. +- Published Topo Project Specification docs: `https://github.com/arm/topo/tree/main/docs/project-specification`, especially `README.md`, `01-authoring-projects.md`, `02-project-configuration.md`, `03-schema.md`, and `05-authoring-best-practices.md`. +- Topo Project Catalog acceptance policy: `https://github.com/arm/topo-project-catalog/blob/main/docs/project-acceptance-criteria.md`. - Published Topo glossary for domain terms: `https://github.com/arm/topo/blob/main/docs/introduction/glossary.md`. - Compose Spec for standard Compose semantics. Do not invent non-standard Compose keys except the root-level `x-topo` extension. When references conflict, prefer the schema for validation behavior, then the specification docs for authoring intent, then the target repository's actual Compose behavior for the smallest safe change. +Keep specification requirements, authoring best practices, and catalog policy distinct. The schema and specification define whether a Project is valid. The authoring best practices provide technical guidance for making Projects accurate, reproducible, adaptable, tested, and fast to iterate. The catalog applies additional curation and acceptance policy. Only apply catalog policy when the user asks about catalog inclusion, submission, acceptance, or readiness. + When validating changes, check if `topo` is installed, and prompt the user for an SSH target to test against. `topo clone dir:./path/to/project` can be used to test project parameters, `topo deploy` can be used to test build and deploy. diff --git a/skills/topo-project-optimize-deployment/references/topo-project-context.md b/skills/topo-project-optimize-deployment/references/topo-project-context.md index 02937133..6b19049c 100644 --- a/skills/topo-project-optimize-deployment/references/topo-project-context.md +++ b/skills/topo-project-optimize-deployment/references/topo-project-context.md @@ -15,10 +15,13 @@ Use Topo vocabulary precisely: Refresh spec-sensitive context at runtime before making or validating Project changes. Authoritative references, in order: - Published Topo Project Specification schema: `https://raw.githubusercontent.com/arm/topo/refs/heads/main/docs/project-specification/schema/topo-project-specification.json`. -- Published Topo Project Specification docs: `https://github.com/arm/topo/tree/main/docs/project-specification`, especially `README.md`, `01-authoring-projects.md`, `02-project-configuration.md`, and `03-schema.md`. +- Published Topo Project Specification docs: `https://github.com/arm/topo/tree/main/docs/project-specification`, especially `README.md`, `01-authoring-projects.md`, `02-project-configuration.md`, `03-schema.md`, and `05-authoring-best-practices.md`. +- Topo Project Catalog acceptance policy: `https://github.com/arm/topo-project-catalog/blob/main/docs/project-acceptance-criteria.md`. - Published Topo glossary for domain terms: `https://github.com/arm/topo/blob/main/docs/introduction/glossary.md`. - Compose Spec for standard Compose semantics. Do not invent non-standard Compose keys except the root-level `x-topo` extension. When references conflict, prefer the schema for validation behavior, then the specification docs for authoring intent, then the target repository's actual Compose behavior for the smallest safe change. +Keep specification requirements, authoring best practices, and catalog policy distinct. The schema and specification define whether a Project is valid. The authoring best practices provide technical guidance for making Projects accurate, reproducible, adaptable, tested, and fast to iterate. The catalog applies additional curation and acceptance policy. Only apply catalog policy when the user asks about catalog inclusion, submission, acceptance, or readiness. + When validating changes, check if `topo` is installed, and prompt the user for an SSH target to test against. `topo clone dir:./path/to/project` can be used to test project parameters, `topo deploy` can be used to test build and deploy. From 9540fd495cab145a54828a291b99a216e320e72e Mon Sep 17 00:00:00 2001 From: James Cox-Morton Date: Mon, 17 Aug 2026 14:16:40 +0100 Subject: [PATCH 3/3] We get it, Topo --- docs/project-specification/05-authoring-best-practices.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/project-specification/05-authoring-best-practices.md b/docs/project-specification/05-authoring-best-practices.md index a8ce9458..9a4f4271 100644 --- a/docs/project-specification/05-authoring-best-practices.md +++ b/docs/project-specification/05-authoring-best-practices.md @@ -1,4 +1,4 @@ -# Topo Project Authoring Best Practices +# Project Authoring Best Practices Recommendations for delivering the best and most consistent user experience with Topo Projects @@ -6,7 +6,7 @@ Recommendations for delivering the best and most consistent user experience with `x-topo` contains attributes that help users discover and use your Project. Ensure you have considered all available attributes in the schema and used them as appropriate. -The [Topo project-authoring skills](https://github.com/arm/topo#project-authoring-skills) can help you lint and improve your Project. +The [Project-authoring skills](https://github.com/arm/topo#project-authoring-skills) can help you lint and improve your Project. ## Only require `topo deploy` to build and run @@ -16,4 +16,4 @@ Running `topo deploy` should be sufficient to build and start the application. D ### Be fast to build and iterate -The best Topo Projects are fast to build, deploy, and iterate on. See [Build Optimization](04-build-optimization.md) or use the [`topo-project-optimize-deployment` skill](https://github.com/arm/topo#project-authoring-skills) for guidance on specific performance best practices. +The best Projects are fast to build, deploy, and iterate on. See [Build Optimization](04-build-optimization.md) or use the [`topo-project-optimize-deployment` skill](https://github.com/arm/topo#project-authoring-skills) for guidance on specific performance best practices.