Skip to content

Define CodeGuard versioning policy in an ADR #139

Open

Description

@thomas-bartlett

Summary

CodeGuard releases can change both security guidance and how that guidance is packaged and installed. Define a versioning policy so contributors can choose release versions consistently and users can understand the compatibility and migration implications of an update.

Record the policy in an architecture decision record (ADR) under docs/adr, covering:

  • What determines a major, minor, or patch release, with examples for guidance changes and packaging or installation changes.
  • Whether content and delivery formats share one version or use separate versions, and why.
  • How to choose a version when both change in the same release.
  • How the policy applies to 1.x maintenance and the planned 2.0 skill release.

Acceptance criteria

Related work

Activity

  1. moved this from Needs Triage to Ready for Owner in Project CodeGuardon Oct 12, 2026
  2. moved this from Ready for Owner to In Progress in Project CodeGuardon Oct 27, 2026
  3. aacarter1 commented on Oct 27, 2026

    @aacarter1
    Contributor
    Release When to use it Examples
    Major (X.0.0) Breaking changes to supported usage, or changes to the established skill strategy. Changing the activation model, replacing the rule-selection strategy, changing required development/review steps, or removing a supported installation format.
    Minor (x.Y.0) New capabilities that preserve existing supported behavior and the established strategy. Adding language or threat coverage, an optional review workflow, a supported host, or an additional installation format.
    Patch (x.y.Z) Corrections and refinements within the existing capabilities and strategy. Fixing an unsafe example, clarifying an existing instruction, correcting a trigger to restore documented activation, or repairing an installer or manifest.
  4. aacarter1 commented on Oct 27, 2026

    @aacarter1
    Contributor

    My proposal is to follow normal semantic versioning (MAJOR.MINOR.PATCH), with an explicit definition of compatibility for CodeGuard. That definition should cover both the security guidance we publish and how the skill activates, selects guidance, and applies it during development.
    Because CodeGuard influences agent behavior, an installation can continue working while the underlying security workflow changes substantially. I would treat those skill strategy changes as major releases.

    For major releases, I think we should explicitly call out these skill strategy changes:

    • Activation: Changing from automatic application during coding to explicit invocation, or making a previously optional review automatic.
    • Rule selection and loading: Replacing mandatory baseline checks and tag/language routing with a different selection model—for example, allowing the agent to decide whether to load previously mandatory guidance.
    • Required workflow: Moving security guidance from code generation into a separate review stage, or introducing a new required sequence of planning, generation, and security review.
    • Primary delivery model: Moving from host-specific rule files to a portable skill as the primary supported integration, even if legacy bundles remain available during the transition.
      These changes should require X.0.0 even when installation paths remain compatible. Users need a clear signal to reassess how CodeGuard fits their development process and to validate the new behavior.
      The boundary matters: editing a skill does not automatically mean changing its strategy. Rewording instructions, splitting reference files, fixing routing defects, or reducing token usage can remain minor or patch changes when they preserve the documented activation model, rule-selection obligations, and required workflow. Changes in measured performance alone should not determine the version increment.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions