Created release schedule (#101)

* RDPP-7470: changes for new test-utils/scaffold * updated release notes * rename to unna * fix link * fix lint (mostly) * updated unna with rdpp-7405 * updated unna with rdpp-7405 * review fixes * corrected shortcode * doc for upgrades * deprecate legacy headers * tweak deprecation * added 7498 notes * added link to Runtime * fixed lint * removed rdpp-7470 docs and reference from release notes * Update data/deprecations.yaml Co-authored-by: Alasdair <alasdairhurst@users.noreply.github.com> * tweaks * changed modules * new release lifecycle * renamed release schedule Co-authored-by: Jamie Peabody <jpeabody@axway.com> Co-authored-by: dvijayakumar <dvijayakumar@axway.com> Co-authored-by: Alasdair <alasdairhurst@users.noreply.github.com> Co-authored-by: Alasdair Hurst <ahurst@axway.com>
Axway · Aug 26, 2022 · 712a2f1 · 712a2f1
1 parent c9ca924
commit 712a2f1
Show file tree

Hide file tree

Showing 32 changed files with 246 additions and 67 deletions.
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# API Builder Docs
+# API Builder style guide
 
 API Builder Docs is a docs-as-code implementation for Axway documentation. It is built using the [Hugo](https://gohugo.io/) static site generator with the [Google Docsy](https://github.com/google/docsy) theme. The site is deployed on Netlify at <https://api-builder-docs.netlify.app//>. Users can edit any documentation page using GitHub web UI or a WYSIWYG editor provided by [Netlify CMS](https://api-builder-docs.netlify.app/).
 
@@ -10,6 +10,24 @@ We welcome your contributions! To get started fork this repository, create a fea
 
 ## Style guide
 
+### Titles
+
+Titles are sentence-case where proper nouns and acronymns are capitalized.
+
+> API Builder style guide
+
+> Check your API
+
+### Links
+
+When referencing a document by title, then the link must use the title capitalization (which is sentence-case, not camel-case), e.g.:
+
+> Refer to [API Builder style guide](#api-builder-style-guide) for more information.
+
+When making a general ad-hoc reference that is not the same as the title, then use capitalization as sentence context case dictates.
+
+> When making links in documents, ensure you follow the [rules](#links).
+
 ### Text buttons
 
 When writing about text buttons, these shall be **Bold**, and written exactly as they appear in the UI.

diff --git a/content/en/docs/deprecations/aliases_in_comparason_operators.md b/content/en/docs/deprecations/aliases_in_comparason_operators.md
@@ -18,9 +18,9 @@ This will be the default behavior in all new services.
 
 ## Why are we deprecating this feature
 
-Previously, querying an aliased field could result in an unexpected result. For example, if a composite model has an aliased field `fname`, the expectation is that a query such as `{"fname": { "$nin": ["Tom" ] }` will return all the models except those with a `fname` of `Tom.` However, the actual result is all rows, including those whose `fname` is `Tom`. This is due to the aliased field being treated as a non-existent field.
+Previously, querying an aliased field could result in an unexpected result. For example, if a composite model has an aliased field `fname`, the expectation is that a query such as `{"fname": { "$nin": ["Tom" ] }` will return all the models except those with a `fname` of `"Tom"`. However, the actual result is all rows, including those whose `fname` is `"Tom"`. This is due to the aliased field being treated as a non-existent field.
 
-Now, the aliased field is correctly mapped, and in the example scenario, only those rows whose `fname` is not `Tom` will be returned.
+Now, the aliased field is correctly mapped, and in the example scenario, only those rows whose `fname` is not `"Tom"` will be returned.
 
 ## How does this impact my service
 
@@ -44,6 +44,6 @@ flags: {
 }
 ```
 
-More `default.js` configuration file information can be found here: [Project Configuration](/docs/developer_guide/project/configuration/project_configuration/#flags)
+For more detailed information on the configuration options, see [Project configuration](/docs/developer_guide/project/configuration/project_configuration/#flags).
 
 Once enabled, review your service to ensure that you have no logic in your flows or APIs that depends on the deprecated behavior.
diff --git a/content/en/docs/deprecations/endpoint_content_type.md b/content/en/docs/deprecations/endpoint_content_type.md
@@ -69,6 +69,6 @@ After upgrading, the `enableOverrideEndpointContentType` feature will not be act
 }
 ```
 
-More `conf/default.js` configuration file information can be found here: [Project Configuration](/docs/developer_guide/project/configuration/project_configuration/#flags).
+For more detailed information on the configuration options, see [Project configuration](/docs/developer_guide/project/configuration/project_configuration/#flags).
 
 Once enabled, review your service to ensure that you have no logic in your flows or APIs that depends on the deprecated behavior.
diff --git a/content/en/docs/deprecations/exit_on_plugin_failure.md b/content/en/docs/deprecations/exit_on_plugin_failure.md
@@ -44,6 +44,6 @@ flags: {
 }
 ```
 
-More `default.js` configuration file information can be found here: [Project Configuration](/docs/developer_guide/project/configuration/project_configuration/#flags)
+For more detailed information on the configuration options, see [Project configuration](/docs/developer_guide/project/configuration/project_configuration/#flags).
 
 Once enabled, review your service to ensure that you have no logic in your flows or APIs that depends on the deprecated behavior.
diff --git a/content/en/docs/deprecations/exit_on_swagger_schema_validation_error.md b/content/en/docs/deprecations/exit_on_swagger_schema_validation_error.md
@@ -40,6 +40,6 @@ flags: {
 }
 ```
 
-More `default.js` configuration file information can be found here: [Project Configuration](/docs/developer_guide/project/configuration/project_configuration/#flags)
+For more detailed information on the configuration options, see [Project configuration](/docs/developer_guide/project/configuration/project_configuration/#flags).
 
 Once enabled, review your startup log to ensure that the service has no invalid JSON schemas or invalid Swagger. If the application starts without error, then the upgrade is successful.
diff --git a/content/en/docs/deprecations/legacy_headers.md b/content/en/docs/deprecations/legacy_headers.md
@@ -0,0 +1,74 @@
+---
+title: Change in default behavior for HTTP response headers
+weight: 56
+deprecation: D056
+date: 2022-08-26
+---
+
+{{% alert title="Note" color="primary" %}}This document describes deprecation {{% deprecation/link D056 %}}{{% /alert %}}
+
+HTTP responses from {{% variables/apibuilder_prod_name %}} automatically include headers for "server", "content-md5", and "etag" by default (unless explicitly configured to be disabled in [`http.headers` configuration](/docs/developer_guide/project/configuration/project_configuration)).
+
+This behavior has been deprecated since {{% variables/apibuilder_prod_name %}} - [Unna](/docs/release_notes/unna) release.
+
+Beginning with the [Unna](/docs/release_notes/unna) release, the HTTP headers "server", "content-md5", and "etag" are regarded as legacy headers, and will not be sent unless explicitly enabled in [`http.headers` configuration](/docs/developer_guide/project/configuration/project_configuration).
+
+This will be the default behavior in all new services.
+
+## Why are we deprecating this feature
+
+The "server" header is used to identify the product and version of the server, e.g. `server: API Builder/4.93.0`. It is excluded by default for security purposes. If included in HTTP responses, it can aid attackers in targeted exploits.
+
+The "etag" (or [entity tag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag)) identifies a specific version of a resource that can be used for caching by the browser. The "etag" is computationally expensive and not necessary if clients do not use it. It is excluded by default for performance purposes.
+
+The "content-md5" is a MD5 hash of the HTTP response, and is used to ensure the response body was not tampered with between the server and the client. It is computationally expensive and not necessary if clients do check the header or if more modern security mechanisms are in place (e.g. TLS). It is excluded by default for performance purposes.
+
+## How does this impact my service
+
+All new services will have "server", "content-md5", and "etag" disabled by default.
+
+Any existing services will continue to work as they previously did, though it is strongly recommended you upgrade the service. Note that the upgrade is a change of behavior that may impact existing clients that rely on "server", "etag" or "content-md5".
+
+## Upgrading existing services
+
+Updates contain important changes to improve the performance, stability, and security of your services. Installing them ensures that your software continues to run safely and efficiently.
+
+It is strongly recommended you upgrade {{% variables/apibuilder_prod_name %}} to the latest version as well any data connectors you may have in your stack. This feature requires a minimum of:
+
+* {{% variables/apibuilder_prod_name %}} - [Unna](/docs/release_notes/unna)
+
+After upgrading, the `disableLegacyHeaders` feature will not be active until you enable it. To enable it, add the following setting to your `default.js` file.
+
+```javascript
+flags: {
+    disableLegacyHeaders: true
+}
+```
+
+Once `disableLegacyHeaders` is set to `true`, then "server", "content-md5", and "etag" are disabled by default, but the `config.http.headers` section can be used to explicitly enable or disable them.
+
+If your service already has a `config.http.headers`, then your service is not impacted by this change, you can leave the configuration section as-is. Note that any header that is `false` can be deleted as they are now disabled by default.
+
+If your service does not have a `config.http.headers` section, then you need to carefuly consider if your clients are impacted by "server", "content-md5", and "etag", as they will not be sent by default. If clients of your service require "server", "content-md5", or "etag", then you can individually enable them in your `config.http.headers`, e.g.:
+
+```javascript
+http: {
+  // This is the port the service will be bound to. Defaults to 8080.
+  port: parseInt(process.env.PORT) || 8080,
+
+  // When this is true, the service will no longer listen on requests over http.
+  // Disabling http requires 'ssl' to be configured.
+  disabled: false,
+
+  // Controls certain header algorithms.
+  headers: {
+    etag: true
+  }
+},
+```
+
+If "server" is already set to `true`, you should consider disabling it (or deleting it) for [security purposes](#why-are-we-deprecating-this-feature).
+
+For more detailed information on the configuration options, see [Project configuration](/docs/developer_guide/project/configuration/project_configuration/#http).
+
+Once enabled, ensure any clients do not depend on the deprecated behavior.
diff --git a/content/en/docs/deprecations/logging_of_level.md b/content/en/docs/deprecations/logging_of_level.md
@@ -50,6 +50,6 @@ flags: {
 }
 ```
 
-More `default.js` configuration file information can be found here: [Project Configuration](/docs/developer_guide/project/configuration/project_configuration/#flags)
+For more detailed information on the configuration options, see [Project configuration](/docs/developer_guide/project/configuration/project_configuration/#flags).
 
 Once enabled, ensure any applications consuming your service's logs do not depend on the deprecated behavior.
diff --git a/content/en/docs/deprecations/memory_connector_like.md b/content/en/docs/deprecations/memory_connector_like.md
@@ -46,4 +46,4 @@ flags: {
 }
 ```
 
-More `default.js` configuration file information can be found here: [Project Configuration](/docs/developer_guide/project/configuration/project_configuration/#flags)
+For more detailed information on the configuration options, see [Project configuration](/docs/developer_guide/project/configuration/project_configuration/#flags).
diff --git a/content/en/docs/deprecations/model_error_outputs.md b/content/en/docs/deprecations/model_error_outputs.md
@@ -51,7 +51,7 @@ flags: {
 }
 ```
 
-More `default.js` configuration file information can be found here: [Project Configuration](/docs/developer_guide/project/configuration/project_configuration/).
+For more detailed information on the configuration options, see [Project configuration](/docs/developer_guide/project/configuration/project_configuration/#flags).
 
 ### Upgrade existing flows
 

diff --git a/content/en/docs/deprecations/models_no_primary_key.md b/content/en/docs/deprecations/models_no_primary_key.md
@@ -56,7 +56,7 @@ flags: {
 }
 ```
 
-More `default.js` configuration file information can be found here: [Project Configuration](/docs/developer_guide/project/configuration/project_configuration/#flags)
+For more detailed information on the configuration options, see [Project configuration](/docs/developer_guide/project/configuration/project_configuration/#flags).
 
 Once enabled, start {{% variables/apibuilder_prod_name %}} to check for invalid flows and endpoints. If there are any flows or endpoints that are now invalid because of the removed methods, {{% variables/apibuilder_prod_name %}} will fail to start with error messages. For example, an Oracle model called NOPK would generate an error like:
 

diff --git a/content/en/docs/deprecations/null_model_fields.md b/content/en/docs/deprecations/null_model_fields.md
@@ -138,6 +138,6 @@ flags: {
 }
 ```
 
-More `default.js` configuration file information can be found here: [Project Configuration](/docs/developer_guide/project/configuration/project_configuration/#flags)
+For more detailed information on the configuration options, see [Project configuration](/docs/developer_guide/project/configuration/project_configuration/#flags).
 
 Once enabled, review your service to ensure that you have no logic in your flows or APIs that depends on the deprecated behavior.
diff --git a/content/en/docs/deprecations/scoped_config.md b/content/en/docs/deprecations/scoped_config.md
@@ -115,6 +115,6 @@ flags: {
 }
 ```
 
-More `default.js` configuration file information can be found here: [Project Configuration](/docs/developer_guide/project/configuration/project_configuration/#flags)
+For more detailed information on the configuration options, see [Project configuration](/docs/developer_guide/project/configuration/project_configuration/#flags).
 
 Once enabled, review your service to ensure that you have no logic in your flows or APIs that depends on the deprecated behavior.
diff --git a/content/en/docs/deprecations/use_primary_key_type.md b/content/en/docs/deprecations/use_primary_key_type.md
@@ -43,6 +43,6 @@ flags: {
 }
 ```
 
-More `default.js` configuration file information can be found here: [Project Configuration](/docs/developer_guide/project/configuration/project_configuration/#flags)
+For more detailed information on the configuration options, see [Project configuration](/docs/developer_guide/project/configuration/project_configuration/#flags).
 
 {{% alert title="Note" color="primary" %}}Enabling the `usePrimaryKeyType` feature is a breaking change for old releases, and it is recommended that you re-test your service after enabling the feature.{{% /alert %}}
diff --git a/content/en/docs/developer_guide/console/_index.md b/content/en/docs/developer_guide/console/_index.md
@@ -89,7 +89,7 @@ The **Configuration** tab displays the list of configuration files on the {{% va
 
 {{% alert title="Note" color="primary" %}}Edits to these files will trigger a server restart once the files have been saved.{{% /alert %}}
 
-See [Project Configuration](/docs/developer_guide/project/configuration/project_configuration/) for an example and settings.
+See [Project configuration](/docs/developer_guide/project/configuration/project_configuration/) for an example and settings.
 
 ![Configuration tab](/Images/configurations_tab.png)
 
@@ -139,15 +139,12 @@ To create a plugin, select the **Create plugin** link. You are directed to [{{%
 
 The **Updates** tab shows updates and upgrades for installed components. You should always keep your components up to date for the latest features, bug fixes, and security updates.
 
-On startup, _updates_ are checked using npm during development only.
+On startup, {{% variables/apibuilder_prod_name %}} will check npm for updates and upgrades to installed components. This check only happens in development, and never in production. This feature is only available when using maintenance and LTS Node.js versions greater than 12.
 
-_Updates_ are new compatible versions of components that will be installed when running [`npm update`](https://docs.npmjs.com/cli/v8/commands/npm-update).
+* An _update_ means that the are new compatibile versions of components available from npm, and can be installed by running [`npm update`](https://docs.npmjs.com/cli/v8/commands/npm-update).
+* An _upgrade_ means that the next version of the component may introduce breaking changes. Upgrades require extra care and attention before installing.
 
-_Upgrades_ are new versions of components which may introduce breaking changes, and are outside the range allowed by your service's package.json. These require extra care when consuming, and can also require modifications to your service.
-
-Upgrades are not currently displayed, and will be introduced in a future release.
-
-This feature is only available when using maintenance and LTS Node.js versions greater than 12.
+Before installing any upgrade, you should read the release notes very carefully. While some breaking changes are innocuous (for example, the new component requires a higher minimum version of node), some breaking changes can cause parts of your application to cease to function as expected. If this is a possibility, the release notes will explain what to do and may also require manual changes to your application before it will function as expected.
 
 ![Updates tab](/Images/updates_tab.png)
 

diff --git a/content/en/docs/developer_guide/flows/manage_endpoints.md b/content/en/docs/developer_guide/flows/manage_endpoints.md
@@ -1,6 +1,6 @@
 ---
-title: Manage Endpoints
-linkTitle: Manage Endpoints
+title: Manage endpoints
+linkTitle: Manage endpoints
 weight: 10
 date: 2021-10-01
 ---
@@ -11,7 +11,7 @@ An API endpoint provides a way for a client to access your application, such as
 
 {{% alert title="Note" color="primary" %}}A Swagger API endpoint definition file can only be imported once. If you attempt to import a Swagger file for the same API endpoint definition, you will receive a server error message due to conflicting paths.{{% /alert %}}
 
-When designing API to import, you should refer to the apiPrefix section in [Project Configuration](/docs/developer_guide/project/configuration/project_configuration/#apiprefix) for important API design considerations.
+When designing API to import, you should refer to the `apiPrefix` section in [Project configuration](/docs/developer_guide/project/configuration/project_configuration/#apiprefix) for important API design considerations.
 
 To import API endpoints using the {{% variables/apibuilder_prod_name %}} user interface:
 

diff --git a/content/en/docs/developer_guide/plugins.md b/content/en/docs/developer_guide/plugins.md
@@ -5,7 +5,7 @@ weight: 100
 date: 2021-10-01
 ---
 
-{{% variables/apibuilder_prod_name %}} 4.0.0 introduces the concept of plugins. Plugins are regular node modules that are included in your {{% variables/apibuilder_prod_name %}} project's `package.json` file.
+{{% variables/apibuilder_prod_name %}} v4 introduces the concept of plugins. Plugins are regular node modules that are included in your {{% variables/apibuilder_prod_name %}} project's `package.json` file.
 
 {{% variables/apibuilder_prod_name %}} detects plugins by searching for installed modules with the `api-builder-plugin-` prefix. Scoped packages with this prefix will also be detected. These plugins can contain a mixture of different component types.