Spec Kit constitution #121
Conversation
Signed-off-by: Brooke Hamilton <[email protected]>
Signed-off-by: Brooke Hamilton <[email protected]>
Signed-off-by: Brooke Hamilton <[email protected]>
* Add spec-kit PowerShell files * Adjust instructions to use scripts based on OS condition --------- Signed-off-by: Dariusz Porowski <[email protected]>
…ations (#120) lint scripts with `shfmt` lint MD with `markdownlint` --------- Signed-off-by: Dariusz Porowski <[email protected]>
Signed-off-by: Brooke Hamilton <[email protected]>
Updated version to 2.0.0 with significant principle additions and redefinitions for multi-repo support. Signed-off-by: Dariusz Porowski <[email protected]>
Signed-off-by: Dariusz Porowski <[email protected]>
|
|
||
| **Rationale**: Radius is fundamentally an API-driven platform enabling multi-cloud deployments and integration with various tools (Bicep, Terraform, Kubernetes). Clear API contracts ensure developers and platform engineers can collaborate effectively with well-understood interfaces. | ||
|
|
||
| ### II. Idiomatic Code Standards |
There was a problem hiding this comment.
I'd like to see separation of concerns and modularity & reuse added
|
|
||
| ### XIII. Recipe Development Standards (Contrib) | ||
|
|
||
| All Recipes MUST be implemented in either Bicep or Terraform with clear module structure. Recipes MUST include comprehensive README documentation explaining purpose, prerequisites, parameters, and outputs. Parameters MUST have descriptions and sensible defaults where applicable. Recipes MUST follow secure-by-default principles (e.g., disable public access, enable encryption). Recipes MUST be tested in representative environments before contribution. Recipes SHOULD be cloud-agnostic where possible, with cloud-specific variants clearly documented. |
There was a problem hiding this comment.
Shouldn't the application template be cloud-agnostic and the Recipes not? i.e. the Recipes are meant to be written for specific compute platforms
There was a problem hiding this comment.
ToDo: Remove the line about cloud-agnostic.
| <!-- | ||
| Sync Impact Report: | ||
| - Version change: 1.0.0 | ||
| - Modified principles: |
There was a problem hiding this comment.
do we need this for v1.0.0 of the doc?
|
|
||
| - **Go**: Follow *Effective Go* patterns; format with `gofmt`; provide godoc comments for all exported items; minimize exported surface area; leverage Go's simplicity over complex abstractions; handle errors explicitly without suppression | ||
| - **TypeScript**: Follow TypeScript handbook and Backstage guidelines; use ESLint and Prettier; enable strict mode; provide explicit types for public APIs; prefer functional patterns where appropriate | ||
| - **Bicep**: Follow official best practices; use kebab-case for resources, camelCase for parameters; modularize with modules; add parameter descriptions; prefer secure defaults |
There was a problem hiding this comment.
we may want to expand upon this in the future. Radius has a specific flavor of Bicep
There was a problem hiding this comment.
To Do: clarify that we use our own bicep extension that parses our resource types.
|
|
||
| **For Go code (radius repo)**: | ||
|
|
||
| - **Unit tests**: Test individual functions and types in `pkg/` directories, runnable with basic prerequisites only (no external dependencies). Use `make test` to run all unit tests. |
There was a problem hiding this comment.
make test might take a long time without one of the caching test tools
|
|
||
| ### VI. Infrastructure as Code Integration | ||
|
|
||
| All infrastructure-related features MUST support Bicep as the primary authoring experience. Bicep type definitions in `bicep-types/` MUST be generated from TypeSpec definitions and kept in sync through `make generate`. Features SHOULD integrate with Terraform through the Recipe system where appropriate. Kubernetes manifests MUST be supported for native Kubernetes resources through existing integration patterns in `pkg/kubernetes/`. |
There was a problem hiding this comment.
I'm not sure this is the right order from a user perspective. Terraform should be the primary recipe authoring experience since it's more widely-known
There was a problem hiding this comment.
To Do: reword this to favor Terraform
|
|
||
| Design specifications MUST be authored in markdown and stored in the public `design-notes` repository before implementation begins. Significant features MUST follow the issue-first workflow at github.com/radius-project/radius, with community discussion before work begins. Design decisions MUST be documented with clear rationale. Breaking changes MUST be called out explicitly with migration guidance. All commits MUST include a `Signed-off-by` line (Developer Certificate of Origin). | ||
|
|
||
| **Rationale**: As a CNCF sandbox project, transparency and community involvement are essential. Public design discussions ensure better outcomes, build trust with the community, and align with open source governance practices. |
There was a problem hiding this comment.
might want to leave out the "Public design discussions" part. we don't really have public design discussions at the moment
|
|
||
| ### IX. Incremental Adoption & Backward Compatibility | ||
|
|
||
| Features, abstractions, and workflow changes MUST support gradual opt-in rather than forcing a disruptive migration. Breaking changes MUST provide a documented migration path and a deprecation period (minimum two release cycles) before removal. New abstractions MUST start behind feature flags or clearly labeled "experimental" status until validated by real usage. Backward compatibility MUST be maintained within a major version; removal or hard behavioral shifts REQUIRE either a guarded rollout or a MAJOR version bump with explicit migration guidance. Documentation MUST call out required user actions for any change that affects existing workflows. |
There was a problem hiding this comment.
we don't really have an SLA on breaking changes. we haven't published a major version yet.
There was a problem hiding this comment.
To Do: reword this to point out that we try to avoid breaking changes, but Radius has not released a 1.0 so breaking changes are acceptable when necessary. We make no guarantees against breaking changes in any given release until we get to 1.0.
|
|
||
| ### XIV. Documentation Structure and Quality (Docs) | ||
|
|
||
| All documentation MUST follow the Diátaxis framework organizing content into Tutorials, How-To Guides, Reference, and Explanation. Documentation MUST be written in Markdown following the Docsy theme conventions. Code examples MUST be tested and runnable. Screenshots MUST be up-to-date with current UI state. Internal links MUST use Hugo shortcodes for maintainability. Navigation structure MUST support progressive disclosure from beginner to advanced topics. |
There was a problem hiding this comment.
is this the framework we use today?
There was a problem hiding this comment.
To Do: check with PMs
Description
This PR introduces Spec Kit into the design notes repo.
Three changes were made:
specify initwas run on the repo to install Spec Kit/specify.constitutionprompt was run to generate theconstitution.mdfile.Review Instructions
Please review the
constitution.mdfile for accuracy. The core Spec Kit files do not need review.