Improve dynamic plugin docs

frontend/packages/console-dynamic-plugin-sdk/README.md

@@ -63,7 +63,7 @@ Note: this table includes Console versions which currently receive technical sup
 
 ## OpenShift Console Versions vs PatternFly Versions
 
-Each Console version supports specific versions of [PatternFly](https://www.patternfly.org/) in terms
+Each Console version supports specific version(s) of [PatternFly](https://www.patternfly.org/) in terms
 of CSS styling. This table will help align compatible versions of PatternFly to versions of the OpenShift
 Console.
 
@@ -75,6 +75,8 @@ Console.
 | 4.13.x            | 4.x                 |                                       |
 | 4.12.x            | 4.x                 |                                       |
 
+Refer to [PatternFly Upgrade Notes](./upgrade-PatternFly.md) containing links to PatternFly documentation.
+
 ## Shared modules
 
 Console is [configured](./src/shared-modules.ts) to share specific modules with its dynamic plugins.
@@ -266,6 +268,32 @@ It provides access to specific modules exposed by the plugin. It's loaded right
 `exposed-barUtils-chunk.js` is the generated webpack chunk for `barUtils` exposed module. It's loaded
 via the plugin entry chunk (`plugin-entry.js`) when needed.
 
+Plugins may also include other assets, such as JSON localization files that follow the general pattern
+`locales/<lang>/plugin__<plugin-name>.json` or static images referenced from the plugin code.
+
+## Serving plugin assets
+
+Dynamic plugins are deployed on a cluster via OLM operators. Each plugin deployment should include a web
+server that hosts the [generated assets](#generated-assets) of the given plugin.
+
+**Important!** Make sure to configure your plugin web server to use MIME type `text/javascript` for all
+JS assets to avoid any issues with the `X-Content-Type-Options: nosniff` security header used by Console
+when fetching plugin assets via Bridge URL `/api/plugins/<plugin-name>`.
+
+Requests for JS assets not served with the correct MIME type can be blocked by the browser, breaking your
+plugin's functionality.
+
+### Caching
+
+The following table lists important plugin assets that must NOT be cached by the plugin web server.
+
+| Asset                  | Notes                                                          |
+| ---------------------- | -------------------------------------------------------------- |
+| `plugin-manifest.json` |                                                                |
+| `plugin-entry.js`      | Applies only to Console plugin SDK versions 0.0.x              |
+
+We generally recommend disabling caching of any JSON resources hosted by the plugin web server.
+
 ## Plugin development
 
 Run Bridge locally and instruct it to proxy e.g. `/api/plugins/console-demo-plugin` requests directly

frontend/packages/console-dynamic-plugin-sdk/scripts/package-definitions.ts

@@ -11,7 +11,7 @@ type GeneratedPackage = {
   outDir: string;
   /** Package manifest. Note: `version` is updated via the publish script. */
   manifest: readPkg.PackageJson;
-  /** Additional files to copy to the package output directory. */
+  /** Additional files or directories to copy to the package output directory. */
   filesToCopy: Record<string, string>;
 };
 
@@ -35,6 +35,11 @@ const commonFiles: Record<string, string> = {
   'README.md': 'README.md',
 };
 
+const docFiles: Record<string, string> = {
+  docs: 'docs',
+  'upgrade-PatternFly.md': 'upgrade-PatternFly.md',
+};
+
 const getReferencedAssets = (outDir: string) => {
   const baseDir = resolvePath(`${outDir}/lib`);
   const jsFiles = glob.sync('**/*.js', { cwd: baseDir, absolute: true });
@@ -113,7 +118,7 @@ export const getCorePackage: GetPackageDefinition = (
   },
   filesToCopy: {
     ...commonFiles,
-    docs: 'docs',
+    ...docFiles,
     ...getReferencedAssets('dist/core'),
   },
 });

frontend/packages/console-dynamic-plugin-sdk/upgrade-PatternFly.md

@@ -0,0 +1,51 @@
+# PatternFly Upgrade Notes
+
+A dynamic plugin targets one or more versions of OpenShift Console. Each Console version supports
+specific version(s) of [PatternFly](https://www.patternfly.org/) in terms of CSS styling.
+
+Check the [OpenShift Console Versions vs PatternFly Versions][console-pf-versions] table
+for compatibility before upgrading to a newer version of PatternFly.
+
+## Console 4.14 and below
+
+Console provides the following PatternFly 4.x [shared modules][console-shared-modules] to plugins:
+
+- `@patternfly/react-core`
+- `@patternfly/react-table`
+- `@patternfly/quickstarts`
+
+When using code from these packages, make sure to import directly from the package index:
+
+```ts
+// Do _not_ do this:
+import { Button } from '@patternfly/react-core/dist/esm/components/Button';
+// Instead, do this:
+import { Button } from '@patternfly/react-core';
+```
+
+## Console 4.15
+
+All plugins that target OpenShift Console 4.15 should upgrade to PatternFly 5.x to take advantage
+of [PatternFly dynamic modules][console-pf-dynamic-modules].
+
+Any PatternFly related code should be imported via the corresponding package index:
+
+```ts
+// Do _not_ do this:
+import { MonitoringIcon } from '@patternfly/react-icons/dist/esm/icons/monitoring-icon';
+// Instead, do this:
+import { MonitoringIcon } from '@patternfly/react-icons';
+```
+
+## PatternFly resources
+
+- [Major release highlights providing an overview of changes][pf-release-highlights]
+- [Upgrade guide with information about codemods and other resources][pf-upgrade-guide]
+- [Release notes change log that can be searched and filtered][pf-upgrade-release-notes]
+
+[console-shared-modules]: ./README.md#shared-modules
+[console-pf-versions]: ./README.md#openshift-console-versions-vs-patternfly-versions
+[console-pf-dynamic-modules]: ./README.md#patternfly-dynamic-modules
+[pf-release-highlights]: https://www.patternfly.org/get-started/release-highlights/
+[pf-upgrade-guide]: https://www.patternfly.org/get-started/upgrade
+[pf-upgrade-release-notes]: https://www.patternfly.org/get-started/upgrade/release-notes