How ITxPT specifications are created

2021-09-03

The release of new specification versions can be seen as the fundamental driver of all work within the ITxPT community. Therefore, it is of interest to understand the release process from start to finish. It is the same for patch releases, minor and major releases.

Inputs feeding new releases

Two primary input sources are driving the specification release process:

1. Market trends and requirements

2. Implementation feedback

Let’s have a look at them.

1. Market trends and requirements

The Requirements Committee and its working groups collect needs from authorities, operators, and other stakeholders to create and deliver Functional Requirements to the Technical Committee. The requirements drive the technical activities and specification changes – a vital function to secure the customer perspective.

Use cases capture customer needs

The Requirements Committee identifies and documents requirements as use cases to be further defined by working groups dedicated to each topic. Public Transport authorities and operators that are also Strategic or Principal ITxPT members are eligible to participate in the Requirement Committee. This ensures that the ITxPT specification development focuses on the customer’s needs.

The Requirements Committee’s objective is to identify issues on a high level without investigating technical solutions or discussing technical constraints – these are the prerogative of the Technical Committee to investigate.

When the Requirements committee has created its Functional Requirements, confirmed with the Technical Committee that they are actionable, and the Executive Board has approved them, the Technical Committee takes over to find technical solutions to the requirements.

2. Implementation feedback + known issues list

The second primary input to the specification development process is the day-to-day input from the implementation and labeling processes. It is a vital source to validate the specification and detect what needs to be updated. The technical support process generates valuable feedback that is gathered and fed into the update process.

Known issues list

The first step of making any specification issues public is through the “known issues list.” All issues and suggested updates are collected until they can be addressed in an upcoming release. The list is also an input to the roadmap for upcoming releases.

The known issues list is a way to make the issues public before the validation and prepare for the next release. The known issues list also contains recommendations on how to minimize the related problems.  The document is available on the ITxPT GitHub in the repository for each specification section: S01, S02, and S03.

New release delivery

The Technical Committee develops technical solutions to functional requirements from the Requirements Committee and as a response to feedback through the implementation and support process. Like the Requirements Committee, the Technical Committee works in working groups formed around specific topics.

The Technical Committee deliverables are Technical Specifications. When the Technical Committee has written the specifications and the Requirements Committee agrees that they cover the Functional Requirements, the Technical Committee creates test cases and, in some events, also goes through a Proof of Concept (POC) with a supplier.

Release levels

A major specification update affects the compatibility of existing functionality where both the service(s) and their client(s) need to be updated.

A minor release means adding new services or functionality without affecting the functionalities of the previous version. Anything that worked with the latest version should also work after a minor release.

A patch release should not affect implementation at all. Any functionality or service should remain compatible after the update.

READ MORE about what constitutes a major, minor, and patch update.

When to release

It is essential for all involved actors that minor or major releases are not released too frequently since they might require users to update systems or add functionality. Therefore, ITxPT has agreed that the bigger the release, the further in between.

Lead times:

  • Major releases cannot be released more than once a year.
  • Minor releases can be released max twice a year.
  • Patch releases are released “on demand.”

Outcome

As well as lead times for each level of updates, there are also procedures for the updates.

Major update:

  • Includes critical extensions and/or changes of  the current scope based on workgroups and/or project outcomes
  • Technical Committee evaluates the changes, and the Executive Board approves the update

Minor update:

  • Applied based on the return of experiences and feedback from members. It keeps the current scope with some updates to clarify specific points
  • The Technical Committee evaluates the input. The Executive Board approves the update

Patch release:

  • A response to the reporting of errors or bugs.
  • Technical Committee Chair reports it to Technical Committee for short validation

Preview Releases and Public Drafts

As a part of the quality work, specification content can be made publicly available before the actual release in two ways: Preview Releases and Public Drafts.

Preview Release

A Preview Release is an official ITxPT Specification release that may be updated before the final release. The purpose is to have the ability to release a specification available for implementation while still be able to fix critical issues without the problem of compatibility with the specification.

Public Drafts

A Public Draft is a (version of) a specification or other document that ITxPT wishes to release for broader circulation. Unlike Preview Release, which has several promises about its state and how it will be managed, a public draft has none of that per default. Each Public Draft should contain a description of its state, the purpose of the public draft, and any expectations/promises made.

READ MORE about Preview Releases and Public Drafts.

Labeling alignment

For major and minor updates, the labeling process and the compliance tests that the ITxPT labs perform need to be updated to match the new version. Any labeled product or system where the functionality is affected by the update needs to go through a new labeling process to prove compliant with the new specification version. Updated compliance tests will be available within three months after the release of the new specification version.