Introduce the concept of side documents

[martinruefenacht]

Problem

Both the Languages WG and the Hybrid & Accelerator WG require the ability to add bindings to the MPI Standard, but the bindings are not relevant to large parts of the MPI Standard audience. Therefore adding ever more bindings into the core document would clutter it unnecessarily.

Proposal

We want to add a short section to 4.1 which allows the introduction of side documents. These side documents are not bound by the MPI Standard timeline. It will be made clear the side documents are overlapping of core concepts and do not introduce concepts that are not present in the core, but also do not need to allow for everything in the core Standard.

Changes to the Text

Introduction of a single section in either Chapter 1.

Impact on Implementations

Implementors will need to consider which side documents they want to support (development overhead), and be very clear on their various distribution channels the support levels.

Impact on Users

Users will be required to know about the support for every side document from each implementation due to the optional aspect.

References and Pull Requests

Fixed by: PR 694

[schulzm]

We have a terminology mix here - side documents (here), associated documents (website), companion documents (rules and procedures) - are they the same, are they different, do they have different rules?

We should list them all here to introduce the various options with common properties first - within those we probably have the language binding side documents and experimental feature documents, which have additional "semantics"

[wesbland]

Based on the discussion on 2022-09-30:

• We need to unify and better specify the terminology on these documents between the website, procedures document, and this proposal.
• It sounds like this is proposing having at least three categories of documents:
  • Normative side-documents (e.g., new language documents, MQD?, MPIR?)
  • Non-normative side-documents (e.g., exploratory features)
  • Organizational side-documents (e.g. JOD, instructions for preparing the doc)
• This proposal will need to include changes to the procedures that define any new categories.
• We may also need to include (either with this proposal or very soon afterward) changes to the existing documents to make them compatible with the new definitions.

[Wee-Free-Scot]

Decisions from virtual meeting on 19th October 2022

• Normative side-documents -- same procedures as main doc, except no ratification (full proposal 2-votes, errata 1-vote, side-doc committee 0-vote)

  • All languages side-documents would be this category (for example, CUDA bindings, SYCL bindings, HIP bindings, Python bindings -- can be partial coverage or full coverage of MPI concepts/functionality)
  • Intent: always stay as a side-doc, to avoid polluting the main doc

• Non-Normative side-documents -- same as current "associated/companion docs" rules [ED: please check current name] (creation 2-votes, changes 1-vote)

  • Exploratory features would be in this category (for example, continuations, semantics table)
  • Intent: eventually merge into main document, once it is mature enough

• Rules document -- same rules as in current rules document

  • Just the rules document in this category

Notes

• Compatibility references to main doc version would force an update to every side-doc whenever a new version of main doc is released
  • Side-doc update votes can happen during (synchronised with) ratification of main doc version.
• The JOD is a dead document that we should not include it in the rules or reference from the main doc.
• The instructions for building the main doc is not a side-doc and should not be included in the rules.

[Wee-Free-Scot]

@martinruefenacht we've missed the announcement deadline for the Dec'22 meeting -- this issue/PR needs to be updated in time for the Q1'23 meeting or it will miss MPI-4.1 -- we need WG time for redrafting this.

[wesbland]

This wasn't read at the December 2022 meeting. The last opportunity for MPI 4.1 is to have it ready at the March 2022 meeting (and it needs to "pass" the reading).

@martinruefenacht Are you (or is someone else) planning to push this forward or should we move it out of the plan for MPI 4.1?

[martinruefenacht]

@wesbland We will announce a reading for the February meeting.