From dcc3630da919b5d601aeab5b44770d5e481612fe Mon Sep 17 00:00:00 2001 From: Kris West Date: Mon, 17 Jan 2022 16:43:19 +0000 Subject: [PATCH 1/7] Experimental features policy on compliance page --- docs/fdc3-compliance.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/fdc3-compliance.md b/docs/fdc3-compliance.md index 1e88fa529..1a1428137 100644 --- a/docs/fdc3-compliance.md +++ b/docs/fdc3-compliance.md @@ -60,3 +60,15 @@ FDC3 adopts the following deprecation policy: 3. Deprecated features are clearly marked with an `@deprecated` tag and comment in both the documentation and jsDocs appplied to the Typescript sources. 4. Where possible, changes to the behavior of an existing feature should be avoided; consider deprecating it and replacing it with something with a different name/syntax. 5. Breaking change should only be made by in a major version of the Standard. + +## Experimental Features +Occasionaly, a change to FDC3 may be proposed where the design is tentative, and because of this, we need feedback from the community to finalise its inclusion in the standard. In such cases, a feature may be designated as _experimental_ to indicate that its design may change in future and that it is exempted from the normal versioning and deprecation polices in order to facilitate that change. However, designating a feature as experimental is likely to reduce its uptake by the community, hence, this designation should be used sparingly. + +FDC3 adopts the following experimental features policy: + +1. A feature may be designated as experimental where feedback is needed to confirm the final design of that feature, with the goal of including it as a full part of the Standard without the experimental label. +2. A feature should only be designated as experimental where there is a reasonable chance that breaking changes to it's design may be applied, based on feedback received; non-breaking changes (refinements) may already be applied to features defined in the Standard without the experimental designation. +3. Experimental features are clearly marked with an `@experimental` tag and comment in both the documentation and jsDocs appplied to the Typescript sources. +4. Experimental features should be considered optional for compliance purposes, but recommendation for implementation (i.e. the SHOULD keyword is implied). +5. Experimental features are exempted from the normal versioning and deprecation policies that govern changes to FDC3. I.e. breaking changes may be made to experimental features between versions of the FDC3 standard without a major version release. +6. The experimental designation maybe removed from a feature in a minor version release (as this will be considered an additive change). From c930cfcfcf97da3531fbb13beed49a5966156810 Mon Sep 17 00:00:00 2001 From: Kris West Date: Mon, 17 Jan 2022 16:55:00 +0000 Subject: [PATCH 2/7] changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index ca4233af4..972188365 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). * `IntentResolution` now requires the name of the intent raised to included, allowing it to be used to determine the intent raised via `fdc3.raiseIntentForContext()`. ([#507](https://github.com/finos/FDC3/pull/507)) * A Trademarks page was added to acknowledge trademarks used within the Standard not owned by FINOS or the Linux Foundation ([#534](https://github.com/finos/FDC3/pull/534)) * Added details of FDC3's existing versioning and deprecation policies to the FDC3 compliance page ([#539](https://github.com/finos/FDC3/pull/539)) +* Added a new experimental features policy, which exempts features designated as experimental from the versioning and deprecation policies, to the FDC3 compliance page ([#549](https://github.com/finos/FDC3/pull/549)) ### Changed * Consolidated `Listener` documentation with other types ([#404](https://github.com/finos/FDC3/pull/404)) From e1ea82e67d556ae87d6e5ef0f31d4965d0ec6c36 Mon Sep 17 00:00:00 2001 From: Kris West Date: Mon, 17 Jan 2022 16:59:59 +0000 Subject: [PATCH 3/7] Apply suggestions from code review typos --- docs/fdc3-compliance.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/fdc3-compliance.md b/docs/fdc3-compliance.md index 1a1428137..761b1a59a 100644 --- a/docs/fdc3-compliance.md +++ b/docs/fdc3-compliance.md @@ -62,13 +62,13 @@ FDC3 adopts the following deprecation policy: 5. Breaking change should only be made by in a major version of the Standard. ## Experimental Features -Occasionaly, a change to FDC3 may be proposed where the design is tentative, and because of this, we need feedback from the community to finalise its inclusion in the standard. In such cases, a feature may be designated as _experimental_ to indicate that its design may change in future and that it is exempted from the normal versioning and deprecation polices in order to facilitate that change. However, designating a feature as experimental is likely to reduce its uptake by the community, hence, this designation should be used sparingly. +Occasionally, a change to FDC3 may be proposed where the design is tentative, and because of this, we need feedback from the community to finalise its inclusion in the standard. In such cases, a feature may be designated as _experimental_ to indicate that its design may change in future and that it is exempted from the normal versioning and deprecation polices in order to facilitate that change. However, designating a feature as experimental is likely to reduce its uptake by the community, hence, this designation should be used sparingly. FDC3 adopts the following experimental features policy: 1. A feature may be designated as experimental where feedback is needed to confirm the final design of that feature, with the goal of including it as a full part of the Standard without the experimental label. 2. A feature should only be designated as experimental where there is a reasonable chance that breaking changes to it's design may be applied, based on feedback received; non-breaking changes (refinements) may already be applied to features defined in the Standard without the experimental designation. -3. Experimental features are clearly marked with an `@experimental` tag and comment in both the documentation and jsDocs appplied to the Typescript sources. +3. Experimental features are clearly marked with an `@experimental` tag and comment in both the documentation and jsDocs applied to the Typescript sources. 4. Experimental features should be considered optional for compliance purposes, but recommendation for implementation (i.e. the SHOULD keyword is implied). 5. Experimental features are exempted from the normal versioning and deprecation policies that govern changes to FDC3. I.e. breaking changes may be made to experimental features between versions of the FDC3 standard without a major version release. 6. The experimental designation maybe removed from a feature in a minor version release (as this will be considered an additive change). From 2c466c399ed4990fe51b58603531f8f96c1bd1be Mon Sep 17 00:00:00 2001 From: Kris West Date: Thu, 20 Jan 2022 11:52:33 +0000 Subject: [PATCH 4/7] Apply suggestions from code review --- docs/fdc3-compliance.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/fdc3-compliance.md b/docs/fdc3-compliance.md index 965713c80..e0f8584e9 100644 --- a/docs/fdc3-compliance.md +++ b/docs/fdc3-compliance.md @@ -62,13 +62,13 @@ FDC3 adopts the following deprecation policy: 5. Breaking change should only be made in a major version of the Standard. ## Experimental Features -Occasionally, a change to FDC3 may be proposed where the design is tentative, and because of this, we need feedback from the community to finalise its inclusion in the standard. In such cases, a feature may be designated as _experimental_ to indicate that its design may change in future and that it is exempted from the normal versioning and deprecation polices in order to facilitate that change. However, designating a feature as experimental is likely to reduce its uptake by the community, hence, this designation should be used sparingly. +Occasionally, a change to FDC3 may be proposed where the design is tentative, and because of this, we need feedback from the community to finalise its inclusion in the Standard. In such cases, a feature may be designated as _experimental_ to indicate that its design may change in future and that it is exempted from the normal versioning and deprecation polices in order to facilitate that change. However, designating a feature as experimental is likely to reduce its uptake by the community, hence, this designation should be used sparingly. FDC3 adopts the following experimental features policy: 1. A feature may be designated as experimental where feedback is needed to confirm the final design of that feature, with the goal of including it as a full part of the Standard without the experimental label. -2. A feature should only be designated as experimental where there is a reasonable chance that breaking changes to it's design may be applied, based on feedback received; non-breaking changes (refinements) may already be applied to features defined in the Standard without the experimental designation. -3. Experimental features are clearly marked with an `@experimental` tag and comment in both the documentation and jsDocs applied to the Typescript sources. -4. Experimental features should be considered optional for compliance purposes, but recommendation for implementation (i.e. the SHOULD keyword is implied). +2. A feature should only be designated as experimental where there is a reasonable chance that breaking changes to its design may be applied, based on feedback received; non-breaking changes (refinements) may already be applied to features defined in the Standard without the experimental designation. +3. Experimental features are clearly marked with an `@experimental` tag and comment in both the documentation and jsDocs applied to the TypeScript sources. +4. Experimental features should be considered optional for compliance purposes, but recommended for implementation (i.e. the SHOULD keyword is implied). 5. Experimental features are exempted from the normal versioning and deprecation policies that govern changes to FDC3. I.e. breaking changes may be made to experimental features between versions of the FDC3 standard without a major version release. 6. The experimental designation maybe removed from a feature in a minor version release (as this will be considered an additive change). From 776caf93c86beabf181f5f754e003ffbc0ca8bfd Mon Sep 17 00:00:00 2001 From: Kris West Date: Thu, 20 Jan 2022 11:53:16 +0000 Subject: [PATCH 5/7] Apply suggestions from code review --- docs/fdc3-compliance.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fdc3-compliance.md b/docs/fdc3-compliance.md index e0f8584e9..0d4c01381 100644 --- a/docs/fdc3-compliance.md +++ b/docs/fdc3-compliance.md @@ -70,5 +70,5 @@ FDC3 adopts the following experimental features policy: 2. A feature should only be designated as experimental where there is a reasonable chance that breaking changes to its design may be applied, based on feedback received; non-breaking changes (refinements) may already be applied to features defined in the Standard without the experimental designation. 3. Experimental features are clearly marked with an `@experimental` tag and comment in both the documentation and jsDocs applied to the TypeScript sources. 4. Experimental features should be considered optional for compliance purposes, but recommended for implementation (i.e. the SHOULD keyword is implied). -5. Experimental features are exempted from the normal versioning and deprecation policies that govern changes to FDC3. I.e. breaking changes may be made to experimental features between versions of the FDC3 standard without a major version release. +5. Experimental features are exempted from the normal versioning and deprecation policies that govern changes to FDC3. I.e. breaking changes may be made to experimental features between versions of the Standard without a major version release. 6. The experimental designation maybe removed from a feature in a minor version release (as this will be considered an additive change). From 8427fee5dc71c0619a15fb6924024e41e1a6b7af Mon Sep 17 00:00:00 2001 From: Kris West Date: Thu, 20 Jan 2022 11:56:01 +0000 Subject: [PATCH 6/7] Clarify that requirement keywords can still be applied to experimental feature, otherwise assume SHOULD --- docs/fdc3-compliance.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fdc3-compliance.md b/docs/fdc3-compliance.md index 0d4c01381..9eacc7f70 100644 --- a/docs/fdc3-compliance.md +++ b/docs/fdc3-compliance.md @@ -69,6 +69,6 @@ FDC3 adopts the following experimental features policy: 1. A feature may be designated as experimental where feedback is needed to confirm the final design of that feature, with the goal of including it as a full part of the Standard without the experimental label. 2. A feature should only be designated as experimental where there is a reasonable chance that breaking changes to its design may be applied, based on feedback received; non-breaking changes (refinements) may already be applied to features defined in the Standard without the experimental designation. 3. Experimental features are clearly marked with an `@experimental` tag and comment in both the documentation and jsDocs applied to the TypeScript sources. -4. Experimental features should be considered optional for compliance purposes, but recommended for implementation (i.e. the SHOULD keyword is implied). +4. Unless otherwise stated, experimental features should be considered optional for compliance purposes, but recommended for implementation (i.e. the SHOULD keyword is implied). 5. Experimental features are exempted from the normal versioning and deprecation policies that govern changes to FDC3. I.e. breaking changes may be made to experimental features between versions of the Standard without a major version release. 6. The experimental designation maybe removed from a feature in a minor version release (as this will be considered an additive change). From 58a9970de0e14cdc76357376683302d06bee04fc Mon Sep 17 00:00:00 2001 From: Kris West Date: Fri, 29 Apr 2022 10:43:28 +0100 Subject: [PATCH 7/7] Update docs/fdc3-compliance.md --- docs/fdc3-compliance.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fdc3-compliance.md b/docs/fdc3-compliance.md index 5aa96b1c9..0f37f4bfc 100644 --- a/docs/fdc3-compliance.md +++ b/docs/fdc3-compliance.md @@ -71,5 +71,5 @@ FDC3 adopts the following experimental features policy: 3. Experimental features are clearly marked with an `@experimental` tag and comment in both the documentation and jsDocs applied to the TypeScript sources. 4. Unless otherwise stated, experimental features should be considered optional for compliance purposes, but recommended for implementation (i.e. the SHOULD keyword is implied). 5. Experimental features are exempted from the normal versioning and deprecation policies that govern changes to FDC3. I.e. breaking changes may be made to experimental features between versions of the Standard without a major version release. -6. The experimental designation maybe removed from a feature in a minor version release (as this will be considered an additive change). +6. The experimental designation may be removed from a feature in a minor version release (as this will be considered an additive change).