From 100b44ea82c6223c30ef041308d21a6190ec4336 Mon Sep 17 00:00:00 2001 From: Joshua Hursey Date: Mon, 27 Sep 2021 09:04:30 -0500 Subject: [PATCH 1/3] Guidance on ABI stability Signed-off-by: Joshua Hursey --- pmix_governance.tex | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/pmix_governance.tex b/pmix_governance.tex index 4160b7a..1a3205d 100755 --- a/pmix_governance.tex +++ b/pmix_governance.tex @@ -85,6 +85,8 @@ \acrodef{PMI}[PMI]{Process Management Interface} \acrodef{PMIx}[PMIx]{Process Management Interface - Exascale} \acrodef{ASC}[ASC]{Administrative Steering Committee} +\acrodef{API}[API]{Application Programming Interface} +\acrodef{ABI}[ABI]{Application Binary Interface} %%%%%%%%%%%%%%%%%%% % Footers @@ -619,7 +621,7 @@ \subsubsection{Minor Document Changes Guidance}% changes to the attention of the ASC Co-Chairs and Release Managers. The Co-Chairs and Release Managers will evaluate the proposed changes to determine whether they are minor or substantive. -Additionally, all PMIx participants are encouranged to examine +Additionally, all PMIx participants are encouraged to examine and comment on the changes in the pull request to aid the Co-Chairs and Release Managers in their decision. If all Co-Chairs and Release Managers determine that the @@ -631,6 +633,30 @@ \subsubsection{Minor Document Changes Guidance}% the changes will be handled using the full rigorous process as described in Section~\ref{the-standardization-process}. +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\hypertarget{abi-changes-guidance}{% +\subsubsection{Application Binary Interface (ABI) Changes Guidance}% +\label{abi-changes-guidance}} + +An \acf{API} defines how data types, data structures, and functions are represented in source code. +An \acf{ABI} defines how data types, data structures, and functions are represented in machine code for a given system. +An important aspect of an \ac{ABI} is the size, layout, and alignment of data structures. +A stable \ac{ABI} may allow a program compiled with one implementation of the PMIx Standard to run with a different implementation of the PMIx Standard as long as both implementations adhere to the same \ac{ABI}. + +The PMIx Standard should strive to maintain a stable \ac{ABI} to support applications and tools that rely on more than one implementation of the PMIx Standard. +To facilitate such interoperability the PMIx \ac{ASC} will maintain, to the best of their ability, a standard set of headers that are versioned with the PMIx Standard that applications and tools can reference~\footnote{PMIx Headers for ABI Compatibility \url{https://github.com/pmix/pmix-abi}}. + +In recognition that there are circumstances where the \ac{ABI} needs to be modified this section defines some guidance for making such modifications. +Additions to the PMIx interface can occur without breaking \ac{ABI} compatibility. +Deprecating and removing portions of the PMIx interface does break \ac{ABI} compatibility and that process (see Section~\ref{deprecation}) must continue to adhere to the following guidance. +As such the following text focuses on modifications to the existing PMIx interface. + +The PMIx Standard must not modify the \ac{ABI} in minor releases. +All modifications of the \ac{ABI} must occur in a major release. +If a Provisional (see Section~\ref{provisional-acceptance}) change requires a modification of the \ac{ABI} then it is no longer eligible to be included in a minor release and must wait to be included in the next major release. + + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \hypertarget{the-standardization-process}{% From 55d4f5358d6f6a68ad6c2473618b3e128fe12a51 Mon Sep 17 00:00:00 2001 From: Joshua Hursey Date: Fri, 22 Apr 2022 14:32:35 -0500 Subject: [PATCH 2/3] Add versioning ABI guidance per discussion Signed-off-by: Joshua Hursey --- pmix_governance.tex | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/pmix_governance.tex b/pmix_governance.tex index 1a3205d..fb3fa41 100755 --- a/pmix_governance.tex +++ b/pmix_governance.tex @@ -645,16 +645,30 @@ \subsubsection{Application Binary Interface (ABI) Changes Guidance}% A stable \ac{ABI} may allow a program compiled with one implementation of the PMIx Standard to run with a different implementation of the PMIx Standard as long as both implementations adhere to the same \ac{ABI}. The PMIx Standard should strive to maintain a stable \ac{ABI} to support applications and tools that rely on more than one implementation of the PMIx Standard. -To facilitate such interoperability the PMIx \ac{ASC} will maintain, to the best of their ability, a standard set of headers that are versioned with the PMIx Standard that applications and tools can reference~\footnote{PMIx Headers for ABI Compatibility \url{https://github.com/pmix/pmix-abi}}. +To facilitate such interoperability the PMIx \ac{ASC} will maintain a standard set of headers that are versioned in relation to the PMIx Standard document that applications and tools can reference~\footnote{PMIx Headers for ABI Compatibility \url{https://github.com/pmix/pmix-abi}}. In recognition that there are circumstances where the \ac{ABI} needs to be modified this section defines some guidance for making such modifications. Additions to the PMIx interface can occur without breaking \ac{ABI} compatibility. Deprecating and removing portions of the PMIx interface does break \ac{ABI} compatibility and that process (see Section~\ref{deprecation}) must continue to adhere to the following guidance. As such the following text focuses on modifications to the existing PMIx interface. -The PMIx Standard must not modify the \ac{ABI} in minor releases. -All modifications of the \ac{ABI} must occur in a major release. -If a Provisional (see Section~\ref{provisional-acceptance}) change requires a modification of the \ac{ABI} then it is no longer eligible to be included in a minor release and must wait to be included in the next major release. +The PMIx Standard ABI is defined in two parts. +The \textit{PMIx Standard Stable ABI} represents the Stable PMIx Standard elements (see Section~\ref{classes-of-standard}). +The \textit{PMIx Standard Provisional ABI} represents the Provisional PMIx Standard elements (see Section~\ref{classes-of-standard}). +The rationale for this separation is in recognition that Provisional PMIx Standard elements are able to change frequently in response to broad experimentation. +This is in contrast to Stable PMIx Standard elements which are permanent, non-changing parts of the PMIx Standard. + +Both the Stable ABI and Provisional ABI are versioned with two increasing numbers (largely following the Semantic Versioning 2.0.0 specification\footnote{Semantic Versioning \url{https://semver.org/spec/v2.0.0.html}}): +\begin{itemize} +\item \texttt{MAJOR} incremented when the ABI changed in a backward-incompatible manner. +\item \texttt{MINOR} incremented when functionality is added to the ABI in a backward-compatible manner. +\end{itemize} + +The PMIx Standard Stable ABI will increment the \texttt{MAJOR} only in major releases of the PMIx Standard. +The PMIx Standard Stable ABI may increment the \texttt{MINOR} in any release of the PMIx Standard. +The PMIx Standard Provisional ABI may increment either the \texttt{MAJOR} or \texttt{MINOR} in any release of the PMIx Standard. + +The PMIx ASC will maintain a mapping between the PMIx Standard version and the ABI version. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% From d5eaf3782c41764439d0c8e703fbf17a8d9aaec6 Mon Sep 17 00:00:00 2001 From: Josh Hursey <4259120+jjhursey@users.noreply.github.com> Date: Thu, 12 May 2022 14:38:27 -0500 Subject: [PATCH 3/3] Revision Exception Changes Wording changes accepted by the revision exception vote. Signed-off-by: Joshua Hursey --- pmix_governance.tex | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/pmix_governance.tex b/pmix_governance.tex index fb3fa41..9cee72f 100755 --- a/pmix_governance.tex +++ b/pmix_governance.tex @@ -649,7 +649,8 @@ \subsubsection{Application Binary Interface (ABI) Changes Guidance}% In recognition that there are circumstances where the \ac{ABI} needs to be modified this section defines some guidance for making such modifications. Additions to the PMIx interface can occur without breaking \ac{ABI} compatibility. -Deprecating and removing portions of the PMIx interface does break \ac{ABI} compatibility and that process (see Section~\ref{deprecation}) must continue to adhere to the following guidance. +Deprecating portions of the PMIx interface does not break \ac{ABI} compatibility but serves as a warning that the \ac{ABI} may be impacted in the future. +Removing portions of the PMIx interface does break \ac{ABI} compatibility and that process (see Section~\ref{deprecation}) must continue to adhere to the following guidance. As such the following text focuses on modifications to the existing PMIx interface. The PMIx Standard ABI is defined in two parts.