|1.0.0||Initial Writing||T Beale||
K Atalag MD (University of Auckland),
R Chen MD (Cambio Health Systems, Sweden),
G Klein MD (Örebro University School of Business),
I McNicoll MD (FreshEhr),
T Nordheim Alme MD (DIPS asa Norway),
S Iancu (Code24, Netherlands)
|19 Dec 2014|
This document describes the Change Management of the openEHR Specification Program, and is part of the governance Terms of Reference for the 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.
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:
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||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.
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.
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.
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.
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.
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.
New CRs are created by the SEC on the relevant Component Change tracker for the relevant Component. The following information is initially required:
Every CR has to initially be accepted or rejected by the SEC. This primarily means determining if:
For every CR accepted, the following information is added:
The Change Owner (assignee) is now responsible for developing the following:
The SEC reviews the CR again. If the impact is deemed acceptable, the CR is allocated to a release.
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.
The initially completed work of a CR is approved as follows:
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:
New specifications can be created in two ways.
All openEHR specifications should include the following standard sections:
In addition, the following sections or information should be included where appropriate:
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.
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.
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.
The Specifications Editorial Committee in concert with the openEHR Management Board.
The Specifications Editorial Committee in concert with the openEHR Management Board.
Resources Learn More