Versioning and Change Management Policy. Report DRAFT

Transcription

1 CEN WS/BII2 Page: 1 (19) CEN WS/BII2 Report DRAFT Version: 2.0 Released: Date of approval:

2 Page: 2 (19) Document Summary The purpose of this report is to define the versioning and change management policy for artefacts, delivered by the BII workshop. Author: - Anders Kingstedt Editors - Oriol Bausà Peris - Georg Birgisson - Fred van Blommestein - Arofan Gregory - Anders Kingstedt Contributors - Jostein Frømyr, EDISYS, NO (vice chair technical coordination) - Sven Rasmussen, Agency of Digitization, Ministry of Finance, Denmark

3 Page: 3 (19) Table of Contents 1 Preamble Versioning and change management policy introduction Background Goals and objectives Versioning Change management (ITSM) Relation to the BII 2 Governance Model Versioning and change management, details Backward compatibility Objects subject to versioning Business rules and information constraints Code lists New elements in a BII profile Name changes Cardinality Phases in a version Version levels numbering Major version numbers Minor version changes Revisions Outstanding issues and considerations Conclusions References and sources... 19

4 Page: 4 (19) 1 Preamble The objective of the CEN Workshop on Business Interoperability Interfaces for public procurement in Europe CEN ISSS WS/BII is to provide a framework for interoperability in pan-european electronic procurement transactions, expressed as a set of technical specifications that cross-refer to relevant activities, and in particular are compatible with UN/CEFACT - in order to ensure global interoperability. The workshop focuses on implementation facilitations and co-coordinating pilots implementing the technical specifications output. The requirements and final specifications are input into UN/CEFACT. The original CEN ISSS BII workshop was concluded in December 2009, and its results were issued as CWA 16073:2010. In early 2010, a second Workshop CEN ISSS WS/BII2 1 was initiated to follow up on and improve the work created in the first workshop. The purpose of the second phase of the workshop on Business Interoperability Interfaces for public procurement in Europe is to establish a forum for development and governance, by: - Providing technical support for adopters and implementers of the BII deliverables; - Providing a forum for governance, life cycle management and further refinements of the CWA published by CEN ISSS WS/BII; - Contributing to coordination and harmonization amongst European initiatives addressing various aspects of e-procurement; - Actively cooperating with the relevant organisations to ensure that European requirements are catered for in international standards and initiatives. Based on user input the CEN ISSS WS/BII2 have reviewed and updated a number of the profiles published as part of CWA 16073: If not otherwise specifically stated, all references to BII or BII2 or CEN WS/BII refers to the second workshop ( BII2 ) of the CEN WS/BII.

5 Page: 5 (19) 2 Versioning and change management policy - introduction 2.1 Background This document suggests a policy for versioning and change management. The use of policy is deliberate. This document presents recommendations that together form the policy for versioning and change management. As the solution for long term governance is to be decided (as of April 2012), it is simply not relevant to construct actual directives and check-lists. The policy document should therefore be regarded as a guiding document that has been put together to reflect the versioning and change management requirements captured during the CEN ISSS WS/BII2. Versioning can be challenging. It involves creating a reasonably comprehensive versioning-system that is not overly complex and that allows for making changes with full knowledge of the impact of any change. Versioning and change management go hand in hand. It is important to maintain full control over the implication of any change. Otherwise the consequences of might inadvertently create a negative result. This is of course especially true for changes affecting the major version level that will result in a breach of the backward compatibility. Another important aspect of change mgmt. is a fully functioning stakeholders communication mechanism. 2.2 Goals and objectives Versioning and the related process, change management, provide control of the BII deliverables within the Governance & Life Cycle management framework. One important objective is to ensure that only necessary changes are made to the elements subject to versioning. Another goal is to ensure that backward compatibility is retained if possible. Finally, all changes should be executed with full control and the changes should be communicated to all stakeholders in sufficient time before the changes are effectuated independent of whether the changes affect backward compatibility or not. The objective of the change management mechanism specifically is to capture faults and inconsistencies and correct these and to handle change requests if found appropriate after analysing the impact, time to correct / make change and business value. To the greatest possible extent, fault corrections and change requests should be coordinated with the users (stakeholders). 2.3 Versioning Versioning can be defined as follows: Software versioning is the process of assigning either unique version names or unique version numbers to unique states of computer software. Within a given version number category (major, minor), these numbers are generally assigned in increasing order and correspond to new developments in the software. At a fine-grained level, revision control is often used for keeping track of incrementally different versions of electronic information, whether or not this information is actually computer software (Source: Wikipedia). Or, alternatively: Versioning is the creation and management of multiple releases of a product, all of which have the same general function but are improved, upgraded or customized. The term applies especially to operating systems (OSs), software and Web services. Version control is the practice of ensuring collaborative data sharing and editing among users of systems that employ different versions of a product. The terms "versioning" and "version control" are sometimes used interchangeably even though their technical meanings are different.

6 Page: 6 (19) In software versioning, subsequent releases of a specific product receive numerical identifiers consisting of two or three numbers separated by periods. The first number, called the major number, is increased when there are significant improvements or changes in functionality. The second number, called the minor number, is incremented when there are minor feature changes or significant fixes. The third number, if it exists, is called the revision number. It is added or increased when minor bugs are eliminated. (Source: TechTarget). As pointed out in the section above (Versioning defined by TechTarget), versioning and version control are two different discipines. This document primarily targets versioning. Version control is sometimes regarded as key element of Configuration Management (CM). CM, when applied over the life cycle of a system, provides visibility and control of its performance, functional and physical attributes. CM verifies that a system performs as intended, and is identified and documented in sufficient detail to support its projected life cycle. The CM process facilitates orderly management of system information and system changes for such beneficial purposes as to revise capability; improve performance, reliability, or maintainability; extend life; reduce cost; reduce risk and liability; or correct defects. The relatively minimal cost of implementing CM is returned many fold in cost avoidance. The lack of CM, or its ineffectual implementation, can be very expensive and sometimes can have such catastrophic consequences as failure of equipment or loss of life. CM emphasizes the functional relation between parts, subsystems, and systems for effectively controlling system change. It helps to verify that proposed changes are systematically considered to minimize adverse effects. Changes to the system are proposed, evaluated, and implemented using a standardized, systematic approach that ensures consistency, and proposed changes are evaluated in terms of their anticipated impact on the entire system. CM verifies that changes are carried out as prescribed and that documentation of items and systems reflects their true configuration. A complete CM program includes provisions for the storing, tracking, and updating of all system information on a component, subsystem, and system basis. (Source: Wikipedia). With the above definition in mind, versioning is the actual classification system and version control is the framework of process descriptions, rules and tools necessary in order to ensure that the versioning is enforced in a correct way. Even though the artifacts subject to versioning are not software, the definition still applies to the BII artifacts. The objective of versioning is to maintain control over versions with respect to issues such as backward compatibility, dependencies and audit trails. These issues are described in more detail later in this document. 2.4 Change management (ITSM) Change management involves handling any changes that are proposed through the legitimate channels. Usually, change requests are initiated by the major stakeholder, either as formalized requests for changes or through incident reports forwarded by a helpdesk (or equivalent). A change requests that will create changes to elements on the major level is usually processed by a Change Control Board (CCB). Change management is an IT service management discipline. The objective of change management in this context is to ensure that standardized methods and procedures are used for efficient and prompt handling of all changes to control IT infrastructure, in order to minimize the number and impact of any related incidents upon service. Changes in the IT infrastructure may arise reactively in response to problems or externally imposed requirements, e.g. legislative changes, or proactively from seeking improved efficiency and effectiveness or to enable or reflect business initiatives, or from programs, projects or service improvement initiatives. Change Management can ensure standardized methods, processes and procedures which are used for all changes, facilitate efficient and prompt handling of all changes, and maintain the proper balance between the need for change and the potential detrimental impact of changes. (Source: Wikipedia) As with the definition of versioning, the above definition of change management doesn t apply to its entirety to the BII elements subject of change management. The basic principles however apply. The bottom line of change management is that any request for changes to the current version of a /BII/ element should be handled in a consistent, repetitive and controlled fashion.

7 Page: 7 (19) The basic process is: 1. Creating a change request (in run-time situations: usually a stakeholder; in production situation: usually by a project participant) 2. Processing the change requests. This might entail: filtering, storing (to a CR log), doing an initial impact analysis. 3. Assessing the change request. This might entail: further impact analysis (assessment of business value, cost, affected elements, activities necessary to act on the changes, time etc.). This activity is usually executed by a CCB or equivalent. 4. Executing the changes, which might entail: a. Modeling (architectural work) b. Updating or adding elements (both those affected by the change/correction and those secondary affected) 5. Verifying (quality assuring) the changes. 6. Communicating the changes (publication) A graphical representation of a suggested change request process is depicted below: Figure 1 the change management work flow

8 Page: 8 (19) 3 Relation to the BII 2 Governance Model The CEN ISSS BII2 Report on Long Term Governance Solution outlines possible elements of the BII governance model in section four (4) Governance BII specific considerations. At the core of suggested Governance model is version mgmt. (versioning) and change management. Some of the elements displayed in the model might be regarded as optional and restrictions might affect the ultimate composition of the model. These restrictions are for instance the final solution for long term governance itself; depending on resources and type of organization, context and possible other related factors, the model might be used as a whole or just partially. The below picture provides a high level presentation of the elements of the BII Governance model. Figure 2 - This picture illustrates how the BII 2 Governance model takes input from the requirements and other sources. The model is the foundation for the Governance organization selected to cater for long term governance. * - denotes elements that are included in the main elements of the model, shown to further explain the constituents. The overall goal of the Governance model is to provide guidance for how to govern the BII deliverables in a controlled and secure fashion, given the restrictions in effect and available resources. The Governance model as framework can be used as is or as boilerplate for the Governance structure used by the organization responsible for long term Governance. A more comprehensive description of the whole Governance eco system is depicted in the below mind map, which places versioning and change management in a context.

9 Page: 9 (19) Figure 3 an overview of the BII Governance eco system.

10 Page: 10 (19) 4 Versioning and change management, details This section outlines and suggests elements of the versioning framework for BII deliverables. As the final composition of the BII versioning framework is dependent on the final solution for BII Governance, long term, the versioning elements should be regarded as preliminary. In this section, some terms and elements of particular significance are also further explained. 4.1 Backward compatibility The term Backward compatible, is used to indicate how extensive changes made to an element are. If a version is backward compatible in relation to previous version(s), this means that an element instance of the previous version will validate without faults in the new version. This means that no limitations can be set in relation to the previous version, but only extensions. This means, for instance, that if the recipient of a BII information entity has implemented a version which is backward compatible with the one used by the sender, the recipient will validate the information entity without faults and be able to read the contents of the information entity. Versions on minor and revision level must be backward compatible. 4.2 Objects subject to versioning This section describes (suggests) the BII elements subject to versioning. Further BII elements might be added. The core BII elements subject to versioning are depicted the BII meta model. Figure 4 the BII Meta Model In addition to these elements, other elements used for validation (based on ISO Schematron), presentation (based on W3C XSD Style sheets) and bound syntax (based on UBL or UN/CEFACT XML messages) are also subject to versioning 2. 2 Please note that no consistent version number according to the proposed system exist for the BII elements currently. The suggestion is to add version numbers at the publication of the current CWA.

11 Page: 11 (19) Business rules and information constraints A business rule (previously called process rules ) describes the rules associated with business information. Business rules govern the overall business relationship between the partners that participate in the profile of which the relevant collaboration or transaction is a part. By agreeing on using the profile for trade the parties agree to these business rules. Business rules are normative and will be included in the validation of the BII entity concerned. Normally, adding further details to a business rule will result in the new version not being backward compatible with the previous one. Removing parts of business rule however typically means that it will remain compatible to the previous version. In addition to business rules, information constraints are used to govern how individual information elements are used by applying restrictions to the information entities. These are categorized into hard ( must be adhered to) and soft ( optional ) Code lists Code lists used in BII elements are referred to via their names. Thus a change in the name results in a new code list, including a change in spelling or a change from upper-case to lower-case letters. It is important to note that also the version number of the code list is included in the name, e.g. "<BII Ref>:codelist:taxtypecode-1.1". The addition of new values in an existing code list is regarded as backward compatible changes New elements in a BII profile If a new element is added to a BII profile element, e.g. address to an information model entity, the version will be backward compatible provided that the elements are placed at the end of the class and that they are not mandatory. If not, this calls for a major version change Name changes <This section should describe how name changes to BII elements affects versioning> Cardinality Cardinality determines the number of instances for a profile element. In case of a change of cardinality, the standard will be backward compatible as long as the requirement is being relaxed. If for example a cardinality is changed from 1 to 0..1, from 1..n to 0..n, from 0..1 to 0..n and from 1 to 1..n, backward compatibility will be retained.

12 Page: 12 (19) 4.3 Phases in a version A version of a BII version element will pass through the following phases in its lifetime 3 : Phase name Description Remarks Under development Under consultation Available Mandatory Authorised Under phase out Discontinued It has been notified that work on a new version has started. The version developed has been submitted for consultation and is awaiting comments. The consultation phase has ended, and a new version of the standard has been made available via the Internet. It has been made mandatory for a public authority to support the standard. When a standard is authorised (statutory), private suppliers are required to support the standard when exchanging e business documents with the public sector. It has been announced that the version will be withdrawn. It will not be possible for new enterprises to register support of a version under phase out. The version can only be supported via transformation. The version is being developed for instance on the basis of a known list of faults and preferences. Revisions (see below) are not submitted for consultation. A version may be available for a long time without being made mandatory. A version can remain mandatory without ever having been authorised. Usually, only parts of the BII element will be authorised. The authorisation date must be notified at least six months before the law comes into force. Phase out will typically be made in connection with the publication of a new version. The transformation must be paid for either by the sender or the recipient 3 This section has been copied in its entirety from the Danish OIOUBL versioning strategy guideline and has only been marginally altered. It is not entirely sure if it is applicable to the BII context and should therefore primarily be regarded as inspiration for the BII governance organization.

13 Page: 13 (19) The data diagram below shows the relationship between the various phases. Planned Notification Under development To be submitted for consultation (at the earliest 1 month after notification) Only revisions Under consultation Publication (at the earliest 3 months from start of consultation) Available At least 6-12 months Mandatory At least 3 months Authorized Under phase-out At least 6-12 months Discontinued

14 Page: 14 (19) 4.4 Version levels - numbering Three different version numbers levels - are suggested for the BII elements: - Major / version changes/ - Minor / version changes/ and - Revision Currently, only two major numbers exist: 1.N.N. (or just 1) which indicates an element created and published after CEN/WS BII (first workshop) and 2.N.N (or just 2) which indicates an element created and published 4 after CEN/WS BII2 (second workshop) Major version numbers A major version number can share the same number as a minor version number, but unlike a minor version change, a major version number change is not backward compatible with the previous version. A major version level change is typically triggered by change requests and the decision on whether a change request should be effectuated is taken in the CCB (or equivalent). A major version change is indicated by an adding an integer to the major level (e.g. from to 2.0.0). Notification A major version change must be notified at least <appropriate time frame, e.g. six months> before the release of a major version. The notification should include: - Element name specification - New and previous version number - Context - Rationale - Existing dependencies (affected elements, if any) - Contact information (responsible role) Communication Prior to the release, the version major change should have been published to the CEN BII s website (se previous section). Validity To ensure a smooth transition from a major version to another, it might be useful to establish a grace period during which two different major versions are allowed to run in parallel. This period should be time limited (e g: 12 months must pass from the date on which the new major version is published until it can be made mandatory). When a new major version is made mandatory, the old version may be transferred to a phase-out period. After having received a phase-out status, a given period of time (e g 12 months) will pass until the version is discontinued (i e not longer supported). Note: any decision to move a major version to phase-out status should obviously require a decision by the CCB (or equivalent). 4 Published in fact means to be published after the conclusion of the running WS.

15 Page: 15 (19) Minor version changes A minor version change is typically incurred by changes that do not affect and call for a major version change, e.g. the introduction of a new schema or minor changes made to an existing element. Changes to a minor version must always be backward compatible with the previous version. A minor version level change is typically triggered by change requests and the decision on whether a change request should be effectuated is taken in the CCB (or equivalent). A minor version change is reflected in an addition to the second level numbering, e.g. <Element> to Notification A minor version change must be notified at least <appropriate time frame, e.g. four months before release>. The notification should include: - Element name specification - New and previous version number - Context - Rationale - Existing dependencies (affected elements, if any) - Contact information (responsible role) Communication Prior to the release, the minor change should have been published to the CEN BII s website (se previous section). Validity As with a major version change, a minor version change might include a transition period where the new version is running in parallel to the existing (old) version. After a given period of time, the previous (old) is given phase-out status and the new, replacing version is made the current (mandatory) version Revisions Revisions are primarily done to elements with the purpose of rectifying those faults and defects that prevent the correct use of the standard. The revisions are typically initiated through 1 the expert working on the element subject to revision and/or 2 incidents reported through the helpdesk or other user communications channels in place. Revisions in BII elements can never contain schema changes, and they will always be backward compatible in relation to the previous version. A revision is indicated by a version change in the form of adding an integer at the third, e.g. from <element> to A revision will typically be triggered by changes to the documentation, code lists and Schematron validation of the BII elements. Notification A revision could be notified at least <appropriate time frame, e.g. one month before release> via the BII website. A list of changes in relation to the previous version could be posted to the BII website when the revision is notified. This list will be updated and issued together with the revision. Communication

16 Page: 16 (19) It is recommended that an aggregated list of revisions is published on the BII website on a regular basis, either successively or on a regular interval basis (see the above). Validity As with changes to the major and minor level, it is possible that a revision should be running in parallel with the previous revision for a specified number of days / months before the new revision replaces the previous (old) one. The old revision is the given phase out status.

17 Page: 17 (19) 5 Outstanding issues and considerations This document proposes some but far from all of the core features of versioning and change management. Further work and elaboration is required. This work includes (but is not limited to): 1. Triggers: a comprehensive list of triggers for fault / error corrections and change requests is required. This list should include initiating actor (role), classification directives, rules for handling different classes of triggers etc. 2. Workflows: different class of actions calls for different workflows, some of which might include multiple steps (such as analysis, CCB review, task executing, resource allocation and more) whereas other might involve simple steps. If possible, a few basic workflows serving as boiler plates for the more elaborate work flows should be established. 3. Audit trails / logging: in order to keep track of changes, it would be helpful to add an audit trail to the versioning and change management framework. This would facilitate tracing changes and provide better understanding as to why changes have been done and thus the evolution of an BII element. 4. Quality assurance management: a set of directives for ensuring quality of changes made to the BII elements should be established. 5. Tooling: the tools used for making changes, tracking changes, keeping track of dependencies should be documented and kept up to date. The tools should be referenced from the workflow description(s). 6. Governance model relationship: other elements of the Governance and Life Cycle model potentially affect the composition of the final versioning and change management policy (framework). Cross cutting concerns should be identified with the purpose of providing an appropriate level of support in terms of versioning and change management.

18 Page: 18 (19) 6 Conclusions As pointed out earlier in this document, the versioning and change management framework plays an important part in the Governance eco system. This policy document outlines recommendations that at a later point in time might be regarded as the basis for instructions for versioning and change management. However, since the solution for long term Governance and sustainability is not yet resolved, it is difficult to regard this document as anything than a guiding policy document. It must also be stressed that the BII deliverables are highly dependent on the stakeholders requests, thus far made implementations (of the BII specifications) and the standards to which elements are bound (currently OASIS UBL and UN/CEFACT XML messages). These facts add to the complexity and calls for care deliberation when composing the ultimate instructions.

19 Page: 19 (19) 7 References and sources Wikipedia Software Versioning TechTarget - NITA: Updating and Versioning Strategy for OIOUBL - common standard for e-business document Governance models / standards used as input: o o o o CobIT, ITIL, CMMI, PM3, o ISO o ISO (Quality management - Guidelines for configuration management)