Introduction

This document describes the Change Management Plan of the openEHR Specification Program.

Status

This document is currently in pre-version 1.0 development.

Change Log

Acknowledgements

This document has benefited from review by the following people.

• Koray Atalag, university of Auckland, New Zealand

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: Development, Trial, Stable, Obsolete and Superseded. For specifications developed from scratch within openEHR (i.e. not donated), the management is as follows:

• 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; version changes follow the semver.org rules;
• Stable state: in stable state, the specification is published in a high-quality format. Proposed changes are assessed based on impact to existing implementations.

The intention is to be lightweight when needed, and to manage specifications carefully if and when 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 criteria.

The following table describes the lifecycle states in detail:

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

TBD: Possible variants:

• publish in durable format for Trial period; wiki is truly bad - non-standard, very poor display quality, and editing on most wikis in WSIWYG is truly abysmal.

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 group, and are used to document changes undertaken to the specifications. No change can be made to the specifications without a CR.

For reference, other lifecycle management specifications:

• IHTSDO's Development, Approval, Maintenance and Review of IHTSDO Technical Reports, Guidelines and Standards
• Current openEHR lifecycle;
• openEHR's existing Change Management Plan.

Promotion of Specifications

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 EC 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 owning CMG 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 owning CMG 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 EC 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 EC 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 will normally have a number of Problem Reports (PRs) and Change Requests (CRs) outstanding against it.The processing of PRs and the creation, acceptance and final approval or rejection of CRs is performed by the Program Editorial Committee (EC), formed of representatives from all CMGs.

Problem Reports

PRs raised on the public SPEC tracker are reviewed on a regular basis, and where appropriate, CRs raised. PR review is carried out online by the Editorial Committee 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, 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 the Editorial Committee, based on a consensus discussion or a 2/3 vote.

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.

Creation

New CRs are created by the EC on the SPEC CR tracker . 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.

TBD: we don't actually do this now; currently, more than one component can be affected by one CR. This is actually better CM practice...

Acceptance

Every CR has to initially be accepted or rejected by the EC. 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;
• estimated of number of days' work;
• assignment of a member from the relevant CMG 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;
• classification as minor, major, critical, reflecting the size of change and impact to users.

The Change Owner is now responsible for obtaining the following information from the CMG:

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

The EC 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 CMG 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 the unanimous vote of the CMG members.
    • 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, including the Program members.
  • 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 EC 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 passed, 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 the SPEC project tracker . If the initial need is described in a PR, it will be reviewed by the EC 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 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 Editorial Committee:

• an identifier
• a title
• the affected component, e.g. Reference Model, Archetype Model, Service Model, Query Languages, etc
  • if a new component is needed, a new CMG will also have to be created;
• 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.

1. There may already be a well-developed document or computable artefact that is being offered to the Specification Program. In this case, the EC 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 EC agrees.
2. Alternatively, the need for a completely new specification might be identified, and a fresh development commenced within the EC.

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 a CMG member 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 Specification Program Editorial Committee 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 Editorial Committee, and may cause a CR to be created. CRs are performed by Specification Program 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 Specification Program Editorial Committee in concert with the openEHR Operational Group.

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

The Specification Program Editorial Committee in concert with the openEHR Operational Group.