Merge pull request #1062 from finos/fdc3-2.1-release

FDC3 2.1 release

Author: kriswest

CHANGELOG.md

@@ -8,6 +8,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ### Added
 
+### Changed
+
+### Deprecated
+
+### Fixed
+
+## [FDC3 Standard 2.1](https://github.com/finos/FDC3/compare/v2.0..v2.1) - 2023-09-13
+
+### Added
+
 * Added `CreateInteraction` intent. To be used when a user wants to record an interaction into a system.  New context `Interaction` also introduced. An interaction might be a call, IM, email, a meeting (physical or virtual) or the preparation of some specialist data. ([#747](https://github.com/finos/FDC3/pull/747))
 * Added `TransactionResult` context. A context type representing the result of a transaction initiated via FDC3. Its purpose is to provide a status and message (where needed) for the transaction and MAY wrap a returned context object. ([#761] (https://github.com/finos/FDC3/pull/761))
 * Added a `MalformedContext` error to the `OpenError`, `ChannelError` and `ResolveError` enumerations, to be used when `broadcast`, `open`, `findIntents`, `raiseIntents`, and other related functions are passed an invalid context Object. ([#972](https://github.com/finos/FDC3/pull/972))

docs/agent-bridging/ref/PrivateChannel.broadcast.md

@@ -69,7 +69,7 @@ Hence, the broadcast message should be repeated once for each subscriber, and mo
 {
     "type": "PrivateChannel.broadcast", //modified type for PrivateChannel broadcasts
     "payload": {
-        "channelId": "private-channel-ABC123",
+        "channel": "private-channel-ABC123",
         "context": { /*contextObj*/}
     },
     "meta": {

docs/fdc3-intro.md

@@ -1,6 +1,6 @@
 ---
 id: fdc3-intro
-title: Welcome to FDC3 2.1 (pre-draft)
+title: Welcome to FDC3 2.2 (pre-draft)
 sidebar_label: Introduction
 ---
 

docs/fdc3-standard.md

@@ -1,6 +1,6 @@
 ---
 id: fdc3-standard
-title: FDC3 2.1 (pre-draft)
+title: FDC3 2.2 (pre-draft)
 sidebar_label: Abstract
 ---
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finos/fdc3",
-  "version": "2.0.3",
+  "version": "2.1.0-beta.1",
   "author": "Fintech Open Source Foundation (FINOS)",
   "homepage": "https://fdc3.finos.org",
   "repository": {

schemas/bridging/privateChannelBroadcastAgentRequest.schema.json

@@ -25,7 +25,7 @@
           "title": "PrivateChannelBroadcast Request Payload",
           "type": "object",
           "properties": {
-            "channelId": {
+            "channel": {
               "type": "string",
               "title": "Channel Id",
               "description": "The Id of the PrivateChannel that the broadcast was sent on"

website/README.md

@@ -0,0 +1,62 @@
+# FDC3 website readme
+
+## Releasing new versions of the Standard
+
+To create a new version of the website, a number of NPM scripts need to be run that will create the version and update certain content within it (as automatically as possible). There are then a number of additional manual steps to run.
+
+1. Enter the website directory and make sure the site has been built:
+
+    ```bash
+    cd website
+    npm run build
+    ```
+
+2. Then run the versioning script - this should work cross-platform, but can be brittle...
+    - edit *website/package.json* and replace the version number in the `version` script to the version number you wish to create:
+        `version": "cross-env-shell VERSION=2.1 ...`
+    - Run it:
+
+        ```bash
+        npm run version
+        ```
+
+    - Check the reported version number is as expected and that the scripts ran without errors. 
+
+3. Check that the version script has done what it needs to:
+    - The new website version should exist in _website/versioned_docs_
+        - Links to schema files should have been updated to the versioned links, e.g. check *website/versioned_docs/version-2.1/context/ref/Context.md* has a link like <https://fdc3.finos.org/schemas/2.1/context/context.schema.json> (where '2.1' would be 'next' in the pre-draft)
+        - The overview docs (often called spec.md) should have had '(next)' in their titles replaced with the version, e.g. '(2.1)', e.g. check *website/versioned_docs/version-2.1/api/spec.md*
+    - A new set of schemas should exist in *website/static/schemas*
+        - Check all schema files/folders got copied, including *api/*, *context/*, *bridging/*, *bridgingAsyncAPI/* and the *appd* files.
+        - Check that their `$id` fields were updated to match their new URLs, e.g. *website/static/schemas/2.1/context/context.schema.json* should have an `$id` that looks like: `"$id": "https://fdc3.finos.org/schemas/2.1/context/context.schema.json"` (where '2.1' would be 'next' in the pre-draft)
+        - Check that the appD schema's `version` field has been updated, i.e. *website/static/schemas/2.1/appd.schema.json* should have `"version": "2.1",` (where '2.1' would be 'next' in the pre-draft)
+
+4. Make a number of additional manual changes:
+    - Edit the titles of *website/versioned_docs/version-2.1/fdc3-intro.md* and *website/versioned_docs/version-2.1/fdc3-standard.md* to remove '(pre-draft')
+    - Edit the titles of *docs/fdc3-intro.md* and *docs/fdc3-standard.md* to use the next planned version number
+    - Edit the last Standard version's abstract to update its status and dates, e.g. *website/versioned_docs/version-2.0/fdc3-standard.md*
+    - Edit the new Standard version's abstract  to update its status and dates, e.g. *website/versioned_docs/version-2.1/fdc3-standard.md*
+    - Edit the `Version` element of `themeConfig.navbar.items` in *website/docusaurus.config.js* to include the new version as the first element.
+
+5. Edit CHANGELOG.md to mark the unreleased changes as teh new version and create a new unreleased section for the next version.
+    - Note that the title of the release section usually includes a compare link for the previous version. These are based on tags - the tag needed will not exist yet, but is created in a later step. It should be fine to set it to what the tag name will be.
+
+6. If creating a new NPM module version at the same time, then
+    - Return to the root of the repository (i.e. parent dir of the *website* dir) and edit *package.json*,
+    - Set the `version` filed to the new standard version - but consider appending a beta label, e.g.: `"version": "2.1.0-beta.1",`
+    - The new NPM module will be built and submitted to NPM via a Github action automatically when this PR is merged.
+
+7. Test you changes locally by running the site:
+
+    ```bash
+        cd website
+        npm run build
+        npm run start
+    ```
+
+8. Create a PR and send out details for other maintainers to review and test.
+
+9. Merge the PR - website and NPM module will be deployed automatically.
+
+10. Goto <https://github.com/finos/FDC3/releases> and create a new release and tag for the new version.
+    - Copy the change log into the release description.

website/docusaurus.config.js

@@ -91,10 +91,14 @@ module.exports={
           "position": "right",
           "items": [
             {
-              "label": "2.0",
+              "label": "2.1",
               "to": "/docs/fdc3-intro",
               "activeBaseRegex": "docs/(?!1.0|1.1|1.2|2.0|next)"
             },
+            {
+              "label": "2.0",
+              "to": "/docs/2.0/fdc3-intro",
+            },
             {
               "label": "1.2",
               "to": "/docs/1.2/fdc3-intro"

website/package.json

@@ -9,32 +9,30 @@
     "build-workbench": "cd ../toolbox/fdc3-workbench && npm install && npm run build",
     "copy-workbench": "del-cli static/toolbox/fdc3-workbench && npm run build-workbench && cpy \"../toolbox/fdc3-workbench/build/**\" static/toolbox/fdc3-workbench",
     "copy-explained": "del-cli static/toolbox/fdc3-explained && cpy \"../toolbox/fdc3-explained\" ../website/static/toolbox/",
-    "version": "npm run version:docs && npm run version:schemas && npm run version:appd",
-    "version:docs": "docusaurus-version ${VERSION}",
-    "version:schemas": "cpy static/schemas/next/*.schema.json static/schemas/${VERSION} && replace-in-files --string=/schemas/next --replacement=/schemas/${VERSION} static/schemas/${VERSION}/*.schema.json",
-    "version:appd": "cpy static/schemas/next/appd.schema.json static/schemas/${VERSION} && cpy pages/schemas/next/app-directory.html pages/schemas/${VERSION}",
-    "version:delete": "docusaurus-delete-version ${VERSION}",
-    "postversion:docs": "replace-in-files --string=/schemas/next --replacement=/schemas/${VERSION} versioned_docs/version-${VERSION}/'**/*.md'",
-    "postversion:schemas": "replace-in-files --string=/schemas/next --replacement=/schemas/${VERSION} static/schemas/${VERSION}/*.schema.json",
-    "postversion:appd": "replace-in-files --string='\"version\": \"next\"' --replacement='\"version\": \"${VERSION}\"' static/schemas/${VERSION}/appd.schema.json",
-    "postversion:delete": "rimraf static/schemas/${VERSION} && rimraf pages/schemas/${VERSION}",
+    "version": "cross-env-shell VERSION=2.1 \"echo \\\"Creating version: $VERSION...\\\" && npm run version:docs && npm run version:docs-schema && npm run version:docs-replace && npm run version:schemas && npm run version:schemas-replace && npm run version:appd-replace",
+    "version:docs": "cross-env-shell \"docusaurus docs:version $VERSION\"",
+    "version:docs-schema": "cross-env-shell replace-in-files --string=/schemas/next --replacement=/schemas/$VERSION versioned_docs/version-$VERSION/**/*.md",
+    "version:docs-replace": "cross-env-shell replace-in-files --string=(next) --replacement=($VERSION) versioned_docs/version-$VERSION/*/*.md",
+    "version:schemas": "cross-env-shell cpy static/schemas/next/** static/schemas/$VERSION",
+    "version:schemas-replace": "cross-env-shell replace-in-files --string=/schemas/next --replacement=/schemas/$VERSION static/schemas/$VERSION/*/*.schema.json",
+    "version:appd-replace": "cross-env-shell replace-in-files --string=\"\"next\"\" --replacement=\"\"$VERSION\"\" static/schemas/$VERSION/appd.schema.json",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy",
     "docusaurus": "docusaurus"
   },
   "devDependencies": {
-    "cpy-cli": "4.2.0",
-    "del-cli": "5.0.0",
-    "docusaurus-delete-version": "0.1.1",
-    "replace-in-files-cli": "2.0.0",
-    "replace-json-property": "1.8.0",
-    "rimraf": "5.0.0",
     "@docusaurus/core": "~2.4.1",
     "@docusaurus/preset-classic": "~2.4.1",
     "@docusaurus/theme-mermaid": "~2.4.1",
     "clsx": "^1.2.1",
+    "cpy-cli": "4.2.0",
+    "cross-env": "^7.0.3",
+    "del-cli": "5.0.0",
     "react": "^17.0.2",
-    "react-dom": "^17.0.2"
+    "react-dom": "^17.0.2",
+    "replace-in-files-cli": "2.0.0",
+    "replace-json-property": "1.8.0",
+    "rimraf": "5.0.0"
   },
   "resolutions": {
     "got": "^11.8.5",

website/static/schemas/2.1/api/README.md

@@ -0,0 +1,10 @@
+# Intro
+
+Quicktype, the chosen generation tool currently has some limitations that prevent fully automatic schema generation from the existing TS types. For example it can not handle interfaces that contain methods in their definition. It also fails to generate schemas even if a type contains unused references to other types or interfaces that contain async functions (Promise return types). Therefore, in order to generate the `api\schemas\api.schema.json` some manual intervention was needed.
+
+Once these limitations are not an issue the `api\schemas\t2sQuicktypeUtil.js` script should be moved to the root level of the project and a new npm script `"api-schema-gen": "node t2sQuicktypeUtil.js src/api schemas/api/api.schema.json"` should be added.
+
+`api\schemas\api.schema.json` - partially auto-generated schema from the existing `src\api` types.
+`api\schemas\baseImplementationMetadata.schema.json` - Used by bridging types that leave out the metadata of the calling application as it does not apply to bridging.
+`api\schemas\intentResolution.schema.json` - At the moment it is not possible to auto-generate this due to limitations in the generation tool (quicktype)
+`api\schemas\t2sQuicktypeUtil.js` - Script used to run the generation of the schema from the types. Should be moved to the root level of the repo once fully-automated generation can be achieved.