Change Management Process

Owned by Former user (Deleted)
Last updated: 2023-04-14 by Marcus
5 min read

1 Introduction

This document describes the process for change management of the BoB standard, i.e. the APIs and the MTS specifications. The process includes all steps from the initial idea or need to the completed new version.

1.1 Definitions

  • Change request, CR – Document stating the need for a change.

  • Change manager, CM – Function at Samtrafiken responsible for the change process.

  • BoB contact person – Single contact person of stakeholder.

  • Stakeholder – Organisations that are owners or partners to Samtrafiken (agreement SPA-10).

1.2 Forums

1.3 The object(s) of a change request

  • APIs – description of communication between components.

  • MTS (Mobile Ticket Specification) – specifications of the standard.

  • Schemas - schema files and translation tables which describe in detail how objects and data content are to be formatted.

  • Documentation - the documentation/description about APIs and MTS.

1.4 Qualified to create a change request

  • All stakeholders who have or are about to implement the BoB standard.

  • Samtrafiken.

1.5 Semantic versioning

Given a version number MAJOR.MINOR.PATCH, increment the:

  • Major version when you make incompatible API changes.

  • Minor version when you add functionality in a backwards-compatible manner.

  • Patch version when you make backwards-compatible bug fixes or definition changes.

Reference: https://semver.org/

1.6 Supported versions

The overall intention and goal is that interoperability requirements and business agreeements between participants will dictate which version(s) an implementor has to support.

1.6.2 Server

  • When implementing a server for the first time, our recommendation is that one chooses the latest (major) version.

  • For an existing server implementation.

    • Our recommendation is to support the latest (major) version.

    • But ultimately, interoperability requirements and business agreements, will dictate which version(s) to support.

1.6.2 Client

From an interoperability standpoint, a client might have to support multiple major versions. This is dictated by which server version(s) the client must be able to communicate with.

1.7 Tags on Bitbucket

To make it easier to see differences on Bitbucket tags are used to mark the version.

1.8 Testing and interoperability

All developers are welcome to test against Samtrafikens test environment bob-test.

The test environment support major profile 2019-1.

If all organisations are testing their implementations against the test environment there is a good chance to secure interoperability.

2 Steps in the process

2.1 Process for Major and Minor changes

2.1.1 Initial steps for the change request

  • The initiator describe a need or idea in the bob-tech group.

  • Stakeholders who are affected by the proposed idea have to be involved in the dialogue regarding the CR in bob-tech. The dialogue has to cover technical, organisational and business perspectives.

  • Initiator is responsible for creating a branch according to the instruction for relevant repository at BoB Standard to illustrate the idea from a technical point of view.

  • Initiator writes a change request using the Change Request template where technical, organisational and business consequenses are stated.

  • Change request is sent to bobsupport@samtrafiken.se.

  • Change manager reviews the change request and makes sure that the change has been thoroughly discussed and analysed from all points of view.

  • Change manager creates an issue in Samtrafikens Jira system.

  • The Jira issue number is communicated in bob-tech.

2.1.2 Change request sent for review

  • A Pull Request number is assigned to the branch in Bitbucket.

  • Change manager sends change request, Jira issue number and reference to Pull Request (#PR) to BoB contact persons for review. The time for replying is at least one month and the reply is sent back to the Change manager.

  • BoB contact persons at stakeholders who are affected of the change are responsible for making sure that their organisation goes through with a review regarding technical, organisational and business perspectives.

  • Change manager has to make sure that all stakeholders have answered. The reply can either be “no comments” or a summary of the review comments. If wanted the evaluation template can be used.

  • If a stakeholder gives relevant comments then Samtrafiken and the initiator have to decide whether to adjust the change request accordingly. In that case an updated change request will be sent out with shorter time for review.

2.1.3 Summary and invitation to CAB

  • Change manager invites all BoB contact persons to a CAB meeting.

  • Change manager publishes a summary of all review answers in the Jira issue.

  • Stakeholders who have reviewed the change and had comments must either take part in the CAB meeting or send their decision GO/NO GO by mail to Change manager.

  • BoB contact persons are free to delegate the responsibility to attend the CAB meeting.

2.1.4 CAB meeting

  • The CAB consists of persons with mandate to make decisions.

  • CAB decisions must be in consensus, i.e. NOT a majority decision.

  • CAB meetings are held when needed but at most once a month.

  • Location for CAB meetings are at Kollektivtrafikens hus in Stockholm. However it is also possible to join online.

2.1.5 GO

CAB decides GO

  • The CAB decision must include new versions and a time limit when older version no longer will be supported.

  • Samtrafiken merges the branch and tags the new version number.

  • Samtrafiken updates the Jira issue with new version number and release information. BoB contact persons and bob-tech group are informed about the CAB decision and the update.

  • Samtrafiken updates a table showing supported versions of stakeholders APIs, schemas and MTS on bob.samtrafiken.se.

2.1.6 NO-GO

No consensus in CAB

  • If one or more stakeholder(s) rejects the change request the CAB cannot reach consensus and the decision will be NO GO.

  • The stakeholder(s) rejecting the change must have a thoroughly motivated reason for doing so.

Adjustment of change request

  • The stakeholder(s) who rejected the change is responsible to make adjustments to the branch.

  • Loop back to dialogue with Samtrafiken, initiator and bob-tech group.

2.1.7 Time schedule for process

2.2 Process for Patch

When a change is labelled as patch Samtrafiken is authorised to implement the change without the complete process. However, Samtrafiken is obliged to inform BoB contact persons and the bob-tech group about the change.

3 Templates

3.1 Change Request

3.2 Evaluation