Skip to main content

Issue 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 an issue. The Issues section explains how to submit an issue, whereas this section elaborates on the management of issues and the role of Semantic Treehouse in that process.

The role of issues​

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. Source: BOMOS (Dutch language), BOMOS Deel 2: de verdieping (Dutch language)

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 issues​

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. Source: BOMOS Deel 2: de verdieping (Dutch language)

Managing issues​

Issues have their own lifecycle, so Semantic Treehouse provides functionalities to keep track of them.

By default all newly submitted issues are considered to be open. An issue 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. The issue view by default filters to show only open issues.

View open issues

Issues that are not open are considered closed. An issue should be closed when all required action related the request have been completed. Closed issues 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 an issue between opening and closing, Semantic Treehouse supports the use of different status labels.

Labels are created on a project level, in the 'Edit project' screen. Some environments use the following labels.

  • In progress: an issue 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: an issue is considered to be rejected whenever the explicit decision has been made that the proposed change will not be implemented. An issue can have multiple reasons to be rejected. For example, the issue is not aligned with the vision of the community, or is not technically feasible.
  • Solved: issues 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 an issue.

Edit issue and add label

Searching, filtering and sorting​

The header bar of the issues overview provides functionalities for searching, filtering, sorting issues and creating a new issue.

The search box enables text search for issues. It looks in the issue's title, issue number, issue author and the parent project (not within issue text).

There are four filter options available from the Filter dropdown at the top of the screen:

  • All issues: lists all issues ever posted
  • Open issues: lists all issues that are open and have yet to be solved
  • My issues: lists all issues that have been submitted by you
  • My organizations' issues: lists all issues that have been submitted by people from your organization

The sorting dropdown provides basic sorting capabilities for the issues, based on the date the issue was created or the last comment of that issue, with most recent entries first.

The header has a 'Create new' button that enables users to submit a new issue.

Editing and deleting issues​

After clicking an issue, users with the maintainer role can edit or remove an issue. First click the issue entry, then in the detail view, click the triple dots icon to edit the issue. Removing an issue can then be done by clicking the red trash can icon in the top right corner.

Removing issue with trash can button

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