Skip to content

No home for design principles that bind more than one package #3930

Open

Description

@myasnikovdaniil

Problem

Some constraints are not about one package but bind everything built next, and there is no place to write them.

Two that came out of computeplane (cozystack/community#33, #3280):

  • ApplicationDefinitionSpec has no facility for operator-fixed values, so a chart is the only place they can live.
  • Settability and defaultability are the same property in a structural schema. A field you can default is a field the tenant can override, and a field absent from the schema gets the chart's own default. "Hardened and unreachable" is not expressible in openAPISchema.

Both bind every operator-owned module anyone writes. Neither is recorded anywhere: ApplicationDefinitionSpec in api/v1alpha1/applicationdefinitions_types.go has no comment about it, and the conversion in pkg/registry/apps/application/rest.go is a bare Values: app.Spec.

Decision records in cozystack/community#56 are filed under the proposal they amend, so they are the wrong home for this.

How it should work

docs/agents already has this genre, it just is not called that. image-refs.md says its rules "are the invariants those scripts are required to hold, and each has been broken at least once in a way that shipped". e2e-testing.md has a core principle backed by an audit of 30 PR runs.

Those files mix three things - invariants with rationale, procedure like the make generate checklist, and orientation like the code layout. Extracting the first into a principles doc would give platform constraints a home and leave procedure as procedure.

Activity

  1. added
    kind/documentationCategorizes issue or PR as related to documentation
    area/aiIssues or PRs related to AI agent guides, AGENTS.md, docs/agents/
    triage/acceptedIndicates an issue is ready to be actively worked on
    priority/backlogGeneral backlog priority. Lower than priority/important-longterm
    and removed
    triage/needs-triageIndicates an issue needs triage by a maintainer
    on Sep 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/aiIssues or PRs related to AI agent guides, AGENTS.md, docs/agents/kind/documentationCategorizes issue or PR as related to documentationpriority/backlogGeneral backlog priority. Lower than priority/important-longtermtriage/acceptedIndicates an issue is ready to be actively worked on

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions