change process

introduction

This document describes the Change Management of the openEHR Specification Program. Specifications are divided into major Components (identified in the ‘Component’ column of the current baseline). They are managed by the Specifications Editorial Committee (SEC), according to the process described here. All change and release management is visible online.

specification lifecycle

All specification artefacts, both documentary and computable follow a lifecycle, from inception (or accession, in the case of donated works) to stability to obsolescence. The following formal lifecycle states are recognised: Planning, Development, Trial, Stable, and Retired. For specifications developed from scratch within openEHR (i.e. not donated), the management is as follows:

• Planning state: development of description and scope of new specification, along with relevance and utility.
• Development state: agile development by project group, no formal change management, visibility of documentation and experimental software. By the end of development, an open source reference implementation must be available.
• Trial state: during this period, the specification is managed in a formal way. Issues are reported on an online tracker; changes are recorded on a separate dedicated tracker, ensuring every change to the specification is recorded;
• Stable state: in stable state, the specification is published in a high-quality format. Proposed changes are assessed based on impact to existing implementations.
• Retired state: some specifications inevitably become obsolete, or irrelevant for other reasons, and are promoted to the Retired state.

The intention is to be lightweight when needed, and to manage specifications carefully as they gain widespread use.

Specifications created based on existing software, widespread existing practices etc can enter the lifecycle at the Trial or Stable states if they meet the relevant criteria.

The following table describes the lifecycle states in detail:

Lifecycle State	Period	Publication Format	Versioning*	Change doc	Change Manager	Issue Reporting
Planning	6 months max	Wiki	0.y.z	informal	external development group	Informal
Development	18 months max	Wiki	0.y.z	Change Requests optional; otherwise informal	SEC or external development group	Informal
Trial	2 years max	PDF + computable	x.y.z (x >= 1)	Change Requests	SEC	Problem Reports
Stable	unbounded	PDF + computable	x.y.z	Change Requests	SEC	Problem Reports
Retired	unbounded	Replaced by version marked as ‘Retired’ and relevant meta-data	frozen	n/a	SEC	n/a

* Versioning obeys rules of semver.org; note that version 0.x.y versions do not follow any strict rules.

Lifecycle State	Formal Expression	Implementation Technology Specification(s)	Implementations	Conformance
Development	One formal tool-based expression must exist, in a widely recognised format, prior to promotion to trial state.	At least one ITS must exist prior to promotion to trial state.	one open source reference implementation must exist prior to promotion to Trial state.	n/a
Trial	Tool-based expression maintained.	An ITS should exist for the major technologies in use.	Prior to promotion, at least 2 independent interoperating implementations, preferably in different major technologies at end of period. These may be commercial or open source.	Conformance levels & criteria developed, tested and published.
Stable	Tool-based expression maintained.		Reference implementation maintained.	Industry implementations recognised via conformance testing.
Retired			Reference implementation still available but not maintained.

Problem Reports (PRs) can be raised by anyone, and are designed to capture reports of problems and issues, including new requirements. Change Requests (CRs) can be created only by the Specifications Editorial Committee, and are used to document changes undertaken to the specifications. No change can be made to the specifications without a CR.

promotion of specifications throught the lifecycle

Specifications are promoted to the next lifecycle state when the appropriate time-limit is reached for the current state. A review is held by the SEC 3 months prior to the putative promotion date to determine if the criteria documented above are satisfied. If so, a CR is raised to document the promotion of the artefact(s) on the relevant date, including all changes to documentation, publishing format and actual publication.

If the criteria are not met, the Component Maintainer is asked to ensure that the specification is worked on to ensure that it will meet the promotion criteria. This may require them communicating with teams in the Software Program or elsewhere in order to ensure adequate implementation has been achieved.

If on the due date of promotion, the promotion criteria are still not met, the Component Maintainer is asked to provide a report indicating if it is likely that the conditions can be met in 3 months or less, and outlining what steps will be taken to achieve them. The SEC may accept this and provide a 3 month extension. Alternatively it may reject it, and the specification is then demoted to ‘obsolete’ state.

After one extension period, the SEC again reviews the specfication, and either accepts it for promotion or rejects it, leading to demotion to ‘obsolete’ state.

change management

Seen as a whole, the specification library consists of a number of components, each of which is separately releasable. The canges that can be made to specifications in any component are driven by Problem Reports (PRs) and Change Requests (CRs). The processing of PRs and the creation, acceptance and final approval or rejection of CRs is performed by the Specifications Editorial Committee.

release definition

Releases are defined for each Component, as the organising structure for changes. They are normally defined pragmataically, depending on the needs and interests of the community, as understood by the SEC. For example various ‘easy’ changes may be already described in PRs or CRs, that could be allocated to a release scheduled soon, whereas other changes might be spread over a programme of other releases.

problem reports

PRs raised on the public SPECPR tracker are reviewed on a regular basis by the SEC, and where appropriate, CRs raised. PR review is carried out online by the SEC either when a new PR is raised, or at least every 3 months.

PR review can lead to a number of possibilities. The PR may be rejected, in which case it is resolved as such and closed. For PRs that are accepted, one or more CRs may be created on the relevant Component CR tracker, or the PR may be linked to an existing PR.

PRs that create CRs are referenced by the relevant CRs. When the latter are completed, the relevant PRs are resolved according to the resolutions of the related CRs.

CRs are not created for specifications still in development phase; instead, changes are added to the CR used at creation of the specification.

change requests

CRs are generally raised in response to PRs. However, CRs may also be raised separately by SEC members.

CRs need to be a) prioritised in importance and b) allocated to releases. A pre-requisite therefore is to define one or more future releases, each with an identifier and expected date of delivery. Allocation to a release may be done at any time, and changed as deemed necessary by the SEC.

The lifecycle of a CR is shown below.

creation

New CRs are created by the SEC on the relevant Component Change tracker for the relevant Component. The following information is initially required:

• a short description (i.e. title)
• a description of the problem(s) it addresses, and/or references to relevant PRs
• the associated component within the specification library (if more than one component is affected, a separate CR or Task is created for each component).
• the raiser
• Other key fields such as id, date etc are created automatically.

acceptance

Every CR has to initially be accepted or rejected by the SEC. This primarily means determining if:

• the CR responds to a real need
• if the CR is compatible with the current specification library.

For every CR accepted, the following information is added:

• planned date of completion;
• estimate: estimation of number of days’ work;
• assignee: allocation of an SEC member by the relevant Component Maintainer, who acts as the Change Owner (CO) (who becomes an ‘assignee’ on the CR). The CO’s responsibility is to manage the CR to completion (which occasionally will be an obsolete state) – essentially this means ensuring the process is followed and the actual work is done on time;
• priority: minor, major, critical, reflecting the size of change and impact to users.

The Change Owner (assignee) is now responsible for developing the following:

• impact assessment;
• detailed description of proposed changes;
• revised classification if necessary.

The SEC reviews the CR again. If the impact is deemed acceptable, the CR is allocated to a release.

• for larger CRs, the addition of more assignees from the SEC may be required. The CO manages this.

performing the work

For minor changes, the work usually involves no more than making a small change to one or more documents, and generating other publication formats where relevant. The changes should be committed to a branch or review version of the specification or artefact.

For major changes, the relevant changes should be made in a branch of the specification repository. Additionally, a dedicated wiki page should be created, describing the work, current status, who is performing it, with links to the relevant CR and also the branch version of the work.

approval

The initially completed work of a CR is approved as follows:

• for minor changes, the changes are reviewed by inspection of the relevant document(s) and/or inspection of the changed computable artefact in a relevant tool.
  • Approval requires review by the Component Maintainer.
    • If passed, the change is committed to the specification library.
    • If not, the assignee has one week to re-present the change, when it will re-enter review.
    • If a change is not approved in 3 rounds of review, it is rejected and closed.
• for major changes:
  • an open review is conducted during a defined period, e.g. 30 days, seeking comments from the openEHR membership.
  • At the end of this period, the assignee(s) have 2 weeks to re-present the work, taking into account the review feedback.
  • A 2/3 majority of the SEC is required to approve the final presentation of the work, incorporating review responses.
    • Ideally, concerns (e.g. that the changes are acceptable but insufficient) of dissenting members should be addressed through further CRs, if appropriate.
  • If accepted, the change is committed to the specification library.
  • If not, the review process is re-entered.
  • If a change is not approved in 3 rounds of review, it is rejected and closed.

creation of new specifications

process

New specifications can be proposed by any member of the openEHR community. Formally this is done via either a PR on the SPEC PR tracker, or if the proposer is a Program member, a CR on a Component Change tracker . If the initial need is described in a PR, it will be reviewed by the SEC which may decide to create a CR for it. If this happens, the CR will cover the initial period of establishment of the specification, including its identification and setting of scope.

New specifications need to be compatible with the existing structure and roadmap of the specification library. For a new specification to be added, it has to have an identifier, be located within the existing structure (a new category of specification may require a new location to be defined), and have a scope defined that is consistent with existing specifications. These are issued by the Specifications Editorial Committee prior to the creation of the initial CR for the specification. The new specification could potentially replace one or more existing specifications, in which case the structure and roadmap may be modified; the CR will also document these changes.

Internationalisation and localisation aspects should also be described.

A successful application to add a new specification results in the following being decided by the SEC:

• an identifier
• a title
• the affected Component, e.g. Reference Model, Archetype Model, Service Model, Query Languages, etc, or a new Component may be required;
• a new wiki page where the development form of the specification can be created
• an announcement of the new specification.

New specifications can be created in two ways.

• There may already be a well-developed document or computable artefact that is being offered to the Specification Program. In this case, the SEC would assess the specification for maturity according to the lifecycle described below, and publish it in an appropriate way. A specification meeting the ‘Trial’ or even ‘Stable’ state criteria may be commenced in that state if the SEC agrees.
• Alternatively, the need for a completely new specification might be identified, and a fresh development commenced within the SEC.

specification pro-forma

All openEHR specifications should include the following standard sections:

• Standard front pages including
  • Front page containing identifier, current version and release date
  • Amendment record
  • Copyright notice
  • Trademarks & Acknowledgements
• Standard TOC
• Introduction, including:
  • Purpose
  • Related documents (in openEHR)
  • Nomenclature
  • Status
  • Tools
  • Changes from previous versions
• <<main specification>>
• Standard references section
• Standard end page(s)

In addition, the following sections or information should be included where appropriate:

• Internationalisation and Localisation
• Implementation guidance.

changes to existing trial and stable specifications

Minor changes to specification documents are normally executed by the Component Maintainer making an agreed small change. Validation is performed by internal review, as described above under CR Lifecycle.

Major changes, typically leading to a new major release of a specification, may be performed by a team, although they can just as easily be performed by a single person. Validation is performed via community-wide open review with a published time limit. Review feedback is posted as comments on the CR. See the Acceptance section above under CR lifecycle.

frequently asked questions

Who can report a problem or propose a change to a specification?

Anyone. This is done by creating a Problem Report (PR) on the SPEC PR public issue tracker. The (SEC) reviews these on a regular basis and may decide to create a Change Request on the specification library based on the PR.

Who decides if a change will be performed or rejected?

A change to the specifications proposed on the SPEC PR public tracker will be reviewed by the SEC, and may cause a CR to be created. CRs are performed by SEC members, and will result in change(s) to the specifications. Sometimes CRs may be rejected during processing, in which case no change will be made.

Who prioritises the changes?

The Specifications Editorial Committee in concert with the openEHR Management Board.

Who decides which changes are in the next release of openEHR?

The Specifications Editorial Committee in concert with the openEHR Management Board.