Skip to main content

Change request management

User communities continuously generate and discover new ideas and requirements for existing message specifications. Much like well-known version control systems like GitHub or GitLab, Semantic Treehouse provides users to communicate these ideas by creating Change request. Section Change requests explains how to submit a change request, whereas this section elaborates on the management of change requests and the role of Semantic Treehouse.

The role of change requests​

Perhaps the most important step in open standardization is collecting wishes and requirements. Shared data models are no exception. Collecting wishes and requirements must be done both when drawing up a new standard and when amending an existing standard.

There are several options for collecting wishes and requirements:

  • Setting up an environment (such as Semantic Treehouse, but there's also options like a git repository or wiki) where users can post ideas. Users can also discuss ideas or proposed changes there.
  • Through a formal consultation. A formal question is asked to the user community around the standard data model about future developments, wishes or requirements. Semantic Treehouse supports this process by providing an easy way to share the (parts of the) model that the question is about.
  • By organizing workshops or discussion meetings with the user community and other stakeholders. Current developments can be discussed during these meetings. For example, some user might tell about a new requirement, which then turns out to also be relevant for others. This development may then lead to an extension or some other change of the standard.

Whichever form is chosen, or combination of forms: ultimately this process must lead to a list of wishes and requirements that must be assessed.

Different kinds of change requests​

Not every idea or wish automatically leads to a change proposal for the standard. Broadly speaking, there are the following options:

  • The idea is more of a question that is specific to the implementation at a particular party. This is a common occurrence when an organization has little experience with the standard. In such a case, the community or the standard development organization (if it exists) can offer possible support in solving the problem. It is then not necessary to change the standard.
  • A wish or idea relates to an adjustment or expansion of the existing standard. This may result from changed legislation, changed processes or other changed needs.
  • The proposal relates to a fundamental change or extension of the standard. Think of:
    • New business processes that are supposed to be supported by the standard data model (i.e. change in functional scope).
    • Extension of scope to move beyond semantic interoperability to include technical interoperability, i.e. record how data should be exchanged on the transport layer. For example: specifying that certain XML/JSON messages may only be exchanged via REST API.
    • Application of the standard in new sectors.

Depending on the structure of standard development organization overseeing the maintenance of the standard, a secretariat or supporting experts can already make an initial sorting based on the categories mentioned. An initial estimate can also be made of the impact of a change proposal. By doing this, the final assessment can run more smoothly later on.

Managing change requests​

Change requests have their own life-cycle, so Semantic Treehouse provides functionalities to keep track of them.

By default all newly submitted change requests are considered to be open. A change request is considered open when all the actions related to the request have not been started or completed. It is a request that has not yet been reviewed, solved, rejected, either because the work hasn't started or is still in progress. All open change requests under the tab 'Open change request'. See picture below.

Change requests that are not open are considered closed. A change request should be closed when all required action related the request have been completed. Closed change requests are saved because the discussions and reasoning it contains are important parts of the community's knowledge base.

To keep track of the status of a change requests between opening and closing, Semantic Treehouse supports the use of three different labels:

  • In progress: a change request is typically considered to be in progress when it is still being reviewed and evaluated. Generally speaking, issues with this label are being discussed within the user community to make better sense of its meaning and implications. The other labels refer to outcomes of these discussions.
  • Rejected: a change request is considered to be rejected whenever the explicit decision has been made that the proposed change will not be implemented. A change request can have multiple reasons to be rejected. For example, the change request is not aligned with the vision of the community, or is not technical feasible.
  • Solved: change requests often describe ideas, whishes, or requirements without much information about what the solution that would satisfy these needs could look like. The 'solved' label indicates that the user community has arrived at a solution design, however it is not yet implemented in the standard.

The following picture indicates how to provide a label to a change request.

Remark that the label 'open' is prominently displayed by its own button. All the open change requests are displayed under the tab 'Open change requests', which lists all change requests that are open and have yet to be solved.

There are four tabs at the top of the screen:

  • Open change requests: lists all change requests that are open and have yet to be solved.
  • All change requests: lists all change requests ever posted.
  • CRs from my organizations: lists all change requests that have been submitted by you or other people from your organization.
  • Create new: enables users to submit a new change request.

All change requests (including their label) can then be found in the following overview:

Finally, users with special user rights (maintainers) can remove a change request entirely:

However, please be careful when permanently removing change requests as keeping a good record is an important part of maintaining a knowledge base (i.e. group memory).