openEHR Specification Governance

This skill covers the change process, release management, and lifecycle governance for openEHR specifications. It is based on the official governance documents at specifications.openehr.org/governance.

Related Skills

• authoring — document scaffolding, repo layout, boilerplate structure
• amendment-record — detailed amendment record authoring conventions
• review — pre-release quality review of spec documents (the spec-reviewer and xref-auditor subagents run it across a whole spec or component)

Specification Lifecycle States

Every specification follows a formal lifecycle:

Planning → Development → Trial → Stable
                                    ↓
                                  Paused → Retired

The Specifications Editorial Committee (SEC) reviews promotion criteria three months before target dates. Unmet criteria may trigger a single three-month extension; subsequent failure results in retirement.

The spec_status field in manifest.json and manifest_vars.adoc carries this state in upper case (for example DEVELOPMENT, TRIAL, STABLE, PAUSED, RETIRED; the full list is in ../authoring/references/manifest-spec-entry.md). Keep both copies identical. To promote a spec, confirm that the SEC has approved the promotion, then set spec_status identically in both files.

Versioning

openEHR uses three-part semantic versioning (x.y.z):

• Patch (z): Error corrections and minor additions that do not change semantics
• Minor (y): Significant additions that do not change existing semantics
• Major (x): Semantic changes requiring potential software upgrades or data migration

Documentation-only corrections (typos, clarifications) receive a revision number update without triggering a new release number.

Artifact Types

Problem Reports (PRs)

• Raised by anyone on the public SPECPR Jira tracker
• Document issues, bugs, or requirements against existing specifications
• The SEC reviews PRs every three months
• Reference format in specs: {spec_tickets}/SPECPR-NNN[SPECPR-NNN^]

Change Requests (CRs)

• Created only by SEC members on component-specific Jira trackers (e.g., SPECRM, SPECAM)
• Each CR documents a specific modification to one or more specifications
• CRs reference the PRs they address
• Reference format in specs: {spec_tickets}/SPECRM-NNN[SPECRM-NNN^]
• If the user is not an SEC member, direct them to raise a PR on the SPECPR tracker instead

Change Request Lifecycle

1. Creation

A CR requires: title, description, problem statement or PR references, affected component(s).

2. Acceptance

The SEC determines if the CR addresses real needs. Accepted CRs receive:

• Completion target date
• Work estimate (days)
• Assigned Change Owner (the component maintainer or designee)
• Priority: minor, major, or critical

3. Work Execution

Minor changes (single-document, no semantic impact):

• Edit directly on the working branch
• Generate publication formats for review

Major changes (cross-cutting or semantic):

• Create a development branch
• Track progress on a dedicated wiki page
• 30-day open community review period required before approval

4. Approval

Minor changes:

• Component Maintainer reviews
• Pass → commit to specification library
• Fail → one week to revise (max 3 rounds, then rejected)

Major changes:

• 30-day community review on Discourse specifications forum
• Assignee revises within two weeks based on feedback
• Two-thirds SEC majority vote required
• Max 3 review rounds, then rejected

5. Community Requirement

From Release 1.0 onward, specification changes (excluding documentation-only text updates) must be announced on the Discourse specifications forum, and require implementation in at least one formal software, schema, or technical expression before adoption.

Release Process

Releases organize changes by component. The SEC defines release identifiers and delivery dates, allocating CRs to releases.

Release Naming

• Releases: Release-N.N.N (e.g., Release-1.0.4)
• Fix releases: Release-N.N.NvM (e.g., Release-1.0.4v1) — for post-release corrections

Steps to Create a Release

Read references/release-checklist.md for the full step-by-step checklist.

The high-level process:

1. Jira (a user task, not doable from the repo): ask the user to confirm that all CRs and PRs for the release are closed and the saved searches exist, then continue.
2. manifest.json: Set the release date, verify spec_status for each spec, ensure Jira links are correct, and prepend the next-cycle releases entry with an empty date.
3. Git: Create a release branch (Release-N.N.N), publish in release mode with the exact command in the checklist (do not use /openehr-specs:publish; it builds previews only), commit, and create the annotated tag. Ask the user before pushing.
4. Webhook: The push triggers the specifications.openehr.org server to pull and deploy.

Steps to Fix a Release

Follow the Fix Release section of references/release-checklist.md.

Creating a New Specification

New specifications are proposed via PR or CR. The SEC verifies:

• Identifier assignment (the id field)
• Structural placement within the specification library
• Scope consistency with existing specifications
• Component location

To scaffold the document and its manifest.json entry once identifier and placement are agreed, follow the authoring skill ("Creating a New Specification Document").

Required Structure

All specifications must include:

• Front matter: identifier, version, amendments, copyright
• Introduction: purpose, related documents, status, tools, change history
• Main content
• References
• Internationalization considerations (where relevant)

Entry Paths

1. Mature external offering: SEC assesses maturity; may start at Trial or Stable
2. New development: Starts at Planning state with 0.y.z versioning

Roles