Introduction

Changing the OpenMI Standard has major implications for both OpenMI developers and users. Unfortunately, it is impossible to make such changes backwards compatible. Consequently, when a new OpenMI Standard is released, all model providers must upgrade their models to stay compliant with the latest OpenMI version. The pace at which this happens varies from model provider to model provider, since many model providers only make new releases of their software products on a six month or yearly basis. Hence, after an OpenMI Standard release it can often take a year before the bulk of compliant models are upgraded to the new version. This has implications for the OpenMI users, as they may find that the models they want to use for linked configurations are not compliant to the same OpenMI versions. For this reason a very conservative release strategy for the OpenMI Standard must be adopted. Of course this has to be balanced against the need to implement the change requests from developers and users. If the Standard stays unchanged for too long, variants of the standard will emerge. It is then unlikely that models compliant with such variants will be linkable to models that comply to the official OpenMI Standard, with the result that end users may find that there are supposedly OpenMI compliant models that cannot be linked.

Given all the considerations above, a time period of about two years between OpenMI standard releases seems appropriate. Such a long period between releases puts huge demands on getting the release right both with respect to quality and contents. Rigid procedures must be applied in order to ensure that releases are absolutely bug free and that the content - the functionality the standard provides - meets both current and future demands.

It is important that the procedure of upgrading the OpenMI standard is as open as practically possible. At all stages during the release all documents should be public available and it should be possible for anyone to comment and influence the decisions.

The new OpenMI Standard release is formally not developed by the OpenMI association. Anyone can provide proposals for OpenMI Standard version x+1. However, it is the right and responsibility of the OpenMI Association Executive Committee to select the best proposal.

Scope

These procedures apply only to the OpenMI Standard. Other items, such as the OpenMI software development kit, the configuration editor, guidelines and so on, are not required to follow this procedure (the SDK and the GUI can be made backward compatible, so this is a different story). The standard is only source code and documentation released under the OpenMI.Standard namespace.

Who may make changes to this procedure

Any changes to this procedure must be approved by the OpenMI Association Executive Committee.

Release procedure

The OpenMI Standard release schedule is divided into four periods:

1. OpenMI Standard x+1 change requests period

The change request period starts immediately after the release of OpenMI standard version x. During this period anyone can submit change requests to the standard. Change requests are submitted electronically on the OpenMI web and made public available. Change requests must follow the rules described below in the change request section. The OpenMI Association will within five days after submission of a change request accept or reject a change request (Michiel: Previous and next sentence may require slight rephrasing: Within 5 days the OATC will analyse the change request with respect to (a) procedures follows (b) factual relevance to the standard (not to the SDK or anything else), communicate the result of this analysis, and if the change request fullfills the requirements, list it in the offical OpenMI standard change request section (or something similar). ). Acceptance at this stage only means that the request follows the rules for change requests and that the request relates to the OpenMI Standard (many people are confused about the distinction between e.g. the standard and the SDK). So accepted change requests are not guaranteed to be included in the next OpenMI Standard. Acceptance of change requests will be (somehow) marked on the request on the web. If a request is rejected is will be marked on the web as rejected and the reasoning for rejection is given. If the person submitting a rejected request does not agree on the rejection, the rejection can then be appealed and a final decision will be made at the next OAEC meeting. The collection of incoming change requests will be discussed at every OAEC meeting and when appropriate the end date for submission of change requests (the end of the change request period) will be decided and announced on the OpenMI web. There must be at least a period of three months from the announcement of this date until the date actually occurs. After the end of the change request period the possibilities for on-line submission of change requests on the web is closed. The OpenMI web will also feature a facility for posting comments to change requests.

2. OpenMI Standard x+1 proposal period

This period starts with a call for OpenMI Standard version x+1 proposals. The deadline for submission of proposals is also announced. The proposal period must be at least 4 months. Anyone can submit proposals (it can easily happen that OATC is the only one submitting such proposals, but to make the procedure as open as possible it should be allowed for anyone to provide proposals). As opposed to the change requests, that typically is aimed at one particular feature, proposals must describe the whole Standard. Proposals must be based on the change requests, but there is no limit to how many change requests that will be taken into account or to which extend the proposed standard reflects these change requests. The OpenMI Standard proposals must follow the requirement for such proposals (see Rules for OpenMI Standard proposal requirement below). Proposals are submitted online and will be public available. (What if a change request is not followed by a proposal? E.g. a change request from a non-IT specialist could basically be a request for supporting some functionality! Who is prioritizing the change requests? What do we do if everybody agrees that some functionality must be included, but nobody wants to put the efort in the desin? Maybe unlikely, but anyway))

3. OpenMI Standard x+1 commenting period

When the deadline for submitting proposals is passed a call for comments to the submitted proposals can be posted on the OpenMI web. Comments can be submitted by anyone and must follow the rules for comments to OpenMI standard proposals (see below). Also the deadline for submission of comments is announced. The commenting period must be at least three months. It should also be possible to submit comments to comments.

4. OpenMI Standard x+1 test and documentation period

When the commenting period has expired the OpenMI Executive Committee will decide which proposal is favorable (in case multiple designs have been submitted?). The executive committee will take into account the submitted change requests, the Standard proposal and the comments to this proposal. The evaluation will be carried out according to the OpenMI standard proposal guidelines, which also are publicly available. The OAEC will announce on the web which proposal is selected and reference selected comments from the commenting period that should be taken into account. (The OAEC is not allowed to give new comments at this stage). The authors of the winning proposal will then respond whether they, under those conditions, will elaborate the final release candidate. If they accept then this will be announced and the test and documentation starts. (Test and documentation is carried out by those who submitted the winning proposal). The authors of the winning proposal will then make modifications to the proposed standard according to the comments, write documentation and test according the requirements for documentation and testing (see below). Finally the release is submitted and the OAEC can, if the everything is OK, release the OpenMI Standard version x+1.

If the submitters of the winning proposal decline to complete the OpenMI Standard release under the given conditions, the OAEC can decide to select another candidate or decide to delay the release. In case of the latter the whole release procedure starts from the beginning again (with a new change request submission period). Previous accepted change requests will still be valid.

Rules for OpenMI Standard change requests

  • Anyone can submit change requests.
  • All change requests are made public available
  • Change requests are submitted online on the OpenMI web using the predefined form
  • The following must be provided with the change request:
    • Full name, affiliation, city, country, and e-mail address must be provided.
    • List of OpenMI standard interfaces affected by the change request.
    • List of OpenMI standard schemas affected by the change request.
    • Free text area, where the reasoning for the change request is described.
    • Free text area, where the actual change request is described.
    • Full source code for any changed interface or new interface, including source code xml comments.
    • Full xml schemas for any changed schema or new schema.

Rules for comments to OpenMI standard change requests or OpenMI Standard proposals.

  • Anyone can submit comments to OpenMI Standard change requests.
  • All comments are made public available
  • Change requests are submitted online on the OpenMI web using the predefined form
  • The following must be provided with the change request:
    • Full name, affiliation, city, country, and e-mail address.
    • Free text area where the comment is given.

Rules for OpenMI standard proposals

  • Anyone can submit a OpenMI Standard proposal
  • OpenMI standard proposals are made public available.
  • The following must be provided with an OpenMI Standard proposal:
    • Full name, affiliation, city, country, and e-mail address.
    • List of OpenMI standard interfaces changed.
    • List of OpenMI standard schemas change.
    • Free text area conceptual changes, and the reasoning for those changes are given.
    • Documentation for tests carried out.
    • Zip file containing the full OpenMI standard release. (This means that if no further comments are provided and the OAEX accepts the proposal as is, this zip file can be directly released.)

Test requirements

Since the OpenMI standard simply is implemented interfaces, real unit test cannot be applied to the interfaces themselves. Hence, the purpose of the test is to ensure that things possible with the previous release also are possible with the new release (and in case not, make a sufficient argumentations for why that is). Make sure that features anticipated for the new release actually can be realized.

Specifically the test must involve the following:

  • Ensure that the OpenMI standard can be compiled without any errors or warnings.
  • Ensure that each and every interface and method is described if sufficient details in the source code comments. Ensure that there are no ambiguities and room for misunderstanding in the source code comments.
  • Upgrade the OATC SDK and GUI or equivalent open source software packages and make sure that these compiles without any errors or warnings and that every unit tests runs without any errors.
  • Demonstrate that the proposed standard works with different types of models and components.

Documentation requirements

Only in-code xml comments are required.

4 Comments

  1. This procedure seems pretty OK to me, although OATC should take a more proactive role in step 'OpenMI standard x+1 commenting period' by ensuring that the review process is organised (i.e. either by discussing/reviewing itself, or by searching for reviewers both within and outside OpenMI Association memebers).

    Furthermore, I wonder if the OATC is the one who has to hand propose the new Standard to the AOEC.

  2. The OA does not perform any testing of the components. However, situations could occur where we for sure know that a component is not compliant, even though the provider claims that this is the case. Which actions should we then take?

  3. We have a specific logo that can be used for OpenMI complaint models. Perhaps this procedure should also define more precisely when component providers are allowed to use this logo.

  4. Unknown User (michiel)

    Jan, I suppose some of my comments below are not too relevant as soon as it becomes clearer (to me) how to deal with non-experts who only have a functionality request. E.g. somebody: "In the next version I would like to see parallel computation". Such a person will likely not be able to phrase a change request since he may never really use the standard itself (only indirectly).

    For the rest, well done!

    I hope you do not mind screwing in the text instead of using comments!