Merge pull request #1857 from EnterpriseDB/release/2021-09-20

.github/pull_request_template.md

@@ -1,6 +1,6 @@
 ## What Changed?
 
-Please list, at a high level, what changed in your branch. If you changed content, include the product, guide, and version as applicable.
+Please list, at a high level, what changed in your branch. If you changed content, include the product, section, and version as applicable. **Please remove the user instructions including the examples before merging the PR.**
 
 **Examples**
 
@@ -17,3 +17,4 @@ Please check all boxes that apply (`[ ]` is unchecked, `[x]` is checked)
 - [ ] This PR adds new content
 - [ ] This PR changes existing content
 - [ ] This PR removes existing content
+- [ ] This PR is for a release, please add this tag: 

README.md

@@ -170,6 +170,8 @@ The app is concerned with two different types of redirects that can be defined i
 
 ### Internal Redirects (within Docs 2.0)
 
+*For specific examples of when to use redirects, see: [How to avoid breaking links when reorganizing, consolidating or deprecating content](docs/how-tos/avoid-breaking-links.md).*
+
 #### `redirects`
 
 The `redirects` frontmatter is to be used for redirects internal to Docs. For example, if you had a file `great_file.mdx` with this following frontmatter...
@@ -180,7 +182,17 @@ redirects:
   - "/another_old_path"
 ```
 
-both `/old_path` and `/another_old_path` would redirect to `great_file.mdx`'s current path. This is perfect for setting up redirects when moving a file around within Docs. Redirects created with `redirects` are permanent (301).
+both `/old_path` and `/another_old_path` would redirect to `great_file.mdx`'s current path. This is perfect for setting up redirects when moving a file around within Docs. Redirects created with `redirects` are permanent (301). 
+
+These paths can be absolute (starting with the root of the site) or relative (to the file in which they are contained). For a `/file/at/path/`,
+
+   - Absolute: `/path/to/file/` - redirects requests for /path/to/file to /file/at/path/ 
+   - Relative: `former_child/` - redirects requests for /file/at/path/former_child/ to /file/at/path/
+   - Relative: `../sibling/` - redirects requests for /file/at/sibling/ to /file/at/path/
+
+#### Netlify-specific redirects
+
+Netlify is the hosting service we use for Docs. Netlify-specific redirects can be found in [`/static/_redirects`](static/_redirects). These are generally used for large-scale redirects, such as when renaming or removing an entire product version.
 
 ### Docs 1.0 to Docs 2.0 redirects
 

docs/agreements/branch-and-release.md

@@ -56,6 +56,8 @@ The `develop` branch should always be in a deployable state.
    the second release of the day would be `2021-02-09-a`, third release would
    be `2021-02-09-b`, and so on.
 
+   If there is release of a new version of a product with documentation changes, also tag with this format: product/*prod_key*/*version*. See [Format for tags](doc-release-tag-format.md).
+
 1. Merge `main` into `develop`.
 
 ## Branching Strategies
@@ -127,6 +129,7 @@ Stop the presses, something is seriously wrong with
 1. [Follow the release portion](#release) of the release process, using the hot
    fix branch as the release branch.
 
+
 ### Bug Fix
 
 - **Base branch**: `develop`

docs/agreements/doc-release-tag-format.md

@@ -0,0 +1,22 @@
+| Product                      | Key                                                     | Tag                                |
+|------------------------------|---------------------------------------------------------|------------------------------------|
+| barman                       | barman                                                  | product/barman/*version*           |
+| Backup and Recovery Tool     | bart                                                    | product/bart/*version*             |
+| BDR                          | bdr                                                     | product/bdr/*version*              |
+| Connectors                   | *name*-connector, where *name* is jdbc, net, odbc, or ocl | product/*name*-connector/*version* |
+| EDB Cloud                    | edbcloud                                                | product/edbcloud/*version*         |
+| EDB Postgres Advanced Server | epas                                                    | product/epas/*version*             |
+| Failover Manager             | efm                                                     | product/efm/*version*              |
+| Foriegn Data Wrappers        | *name*-fdw, where *name* is hadoop, mongo, or mysql       | product/*name*-fdw/*version*       |
+| HARP                         | harp                                                    | product/harp/*version*             |
+| Migration Portal             | mp                                                      | product/mp/*version*               |
+| Migration Toolkit            | mtk                                                     | product/mtk/*version*              |
+| Postgres Enterprise Manager  | pem                                                     | product/pem/*version*              |
+| pgBackrest                   | backrest                                                | product/backrest/*version*         |
+| PgBouncer                    | pgbouncer                                               | product/pgbouncer/*version*        |
+| pgPool-II                    | pgpool                                                  | product/pgpool/*version*           |
+| PostGIS                      | postgis                                                 | product/postgis/*version*          |
+| PostgreSQL                   | pgsql                                                   | product/pgsql/*version*            |
+| Replication Manager          | repmgr                                                  | product/repmgr/*version*           |
+| Replication Server           | eprs                                                    | product/eprs/*version*             |
+| Slony                        | slony                                                   | product/slony/*version*            |

docs/how-tos/avoid-breaking-links.md

@@ -0,0 +1,121 @@
+# How to avoid breaking links when reorganizing, consolidating or deprecating content
+
+Once a page has been published, links to it proliferate on the Internet: some in public (documentation, blog posts, search engine results) and some in private (emails, chat history, bookmarks, browser histories). When those links are broken, it results in frustration for readers, loss of traffic, and loss of trust - both the algorithmic "trust" endowed by search engines and the real sort of trust granted by people.
+
+We should do our best to avoid causing frustration. We need that trust! 
+
+Yet, we cannot and should not keep every published file around in the same location forever. It is often necessary to reorganize content, moving files around, moving topics between files, consolidating information from multiple files into one, even removing files, directories, or entire sets of documentation (as when a product version reaches its end of life). 
+
+Fortunately, we have tools available to us in the form of [redirects](https://github.com/EnterpriseDB/docs#redirects) that can allow us to preserve the utility of outstanding links without hindering our ability to curate and manage content. This guide covers their use in several common scenarios.
+
+## Renaming a file
+
+Suppose I have a file: `/product_docs/docs/epas/13/epas_inst_linux/02_supported_platforms.mdx`. The URL for the published version of this file when EPAS 13 is the latest version will be https://www.enterprisedb.com/docs/epas/latest/epas_inst_linux/02_supported_platforms/ (once EPAS 14 is released, it will be https://www.enterprisedb.com/docs/epas/13/epas_inst_linux/02_supported_platforms/). 
+
+I would like to rename this file to be simply, `supported_platforms.mdx`. The URL would then be https://www.enterprisedb.com/docs/epas/latest/epas_inst_linux/supported_platforms/. But I would like the old URL to continue to work!
+
+I can add a redirect rule to the page's Frontmatter for this:
+
+```yaml
+---
+#...
+
+redirects:
+  # note that this is the absolute URL path (not including /docs), NOT a filesystem path
+  - /epas/13/epas_inst_linux/02_supported_platforms  
+---
+```
+
+Now requests to https://www.enterprisedb.com/docs/epas/13/epas_inst_linux/02_supported_platforms/ OR https://www.enterprisedb.com/docs/epas/13/epas_inst_linux/supported_platforms/ will take me to the same file.
+
+But what about https://www.enterprisedb.com/docs/epas/latest/epas_inst_linux/02_supported_platforms/? That will work too - up UNTIL version 13 is no longer the latest version. Suppose I want to write this redirect rule such that it will work for EPAS 13 OR any later version (assuming the file is copied into later versions without modifications to the Frontmatter)? To accomplish this, I can use a relative path:
+
+```yaml
+---
+#...
+
+redirects:
+  # this is relative to /epas/13/epas_inst_linux/02_supported_platforms/ and indicates a (missing) "sibling" 
+  # - so I have to go "up" a level first (with ../) 
+  - ../02_supported_platforms  
+---
+```
+
+This same rule will work, without modification, for ANY version in which `supported_platforms.mdx` exists and `02_supported_platforms.mdx` does not. It thus avoids the housekeeping task of having to modify versions contained within
+redirects when forking a version of the documentation (though do note that if a documentation tree has ALREADY been forked when I rename the file I'll need to make the same changes to both the current version and the next version).
+
+## Relocating a file
+
+Suppose I have a file, `/[whatever]/installation/connecting.mdx`. And I wish to move it to a more appropriate location under `/[whatever]/usage`. I need only include the former path in the redirects to avoid breaking links:
+
+```yaml
+---
+#...
+
+redirects:
+  - /[whatever]/installation/connecting/
+---
+```
+
+This is just a variation on what is shown above (renaming). I could also use a relative path here as well.
+
+## Consolidating files
+
+Suppose I have a collection of files that each tackle part of a topic:
+
+- `/[whatever]/installation/index.mdx` overview of an installer
+- `/[whatever]/installation/supported_platforms.mdx` covers the platforms that are supported by an installer
+- `/[whatever]/installation/prerequesites.mdx` covers what is needed before installation can begin
+- `/[whatever]/installation/download.mdx` covers obtaining the installer
+- `/[whatever]/installation/running.mdx` covers the steps involved in actually running the installer
+- `/[whatever]/installation/post_install.mdx` covers any actions needed after the installer has completed
+
+I decide to move all of these into sections in a single file, `/[whatever]/installation.mdx`. 
+In order to avoid breaking the links, I'll need five `redirects` values:
+
+```yaml
+---
+#...
+
+redirects:
+  # these are relative to /[whatever]/installation/
+  - supported_platforms
+  - prerequesites
+  - download
+  - running
+  - post_install
+---
+```
+
+As in the previous example, by using relative paths I'm able to avoid pinning these to a specific 
+version of the product. Because the new `installation.mdx` is replacing the former `installation/index.mdx` (and will have the same URL path), it does not need to be included.
+
+## Removing an End-of-Life version
+
+The previous examples have all concerned content that must continue to exist in some form, but all good things must come to an end: product versions eventually stop being supported and their documentation is archived and removed. Even then, we can provide a better experience than a 404 (Not Found) result! Consider what we might do for the removal of a product version, let's say EPAS 9.6: instead of dropping all links, we can redirect them to `/epas/latest/` - thus providing a stable link that will not soon go out of date and can provide access to at least *some* relevant information!
+
+Adding these redirects via Frontmatter would be prohibitive: we'd have to add thousands of entries for each deprecated version! A more maintainable solution can be found via [Netlify redirects](../../static/_redirects) - you can view that file for more details, but for our example a rule would look like this:
+
+```
+/docs/epas/9.6/*   /docs/epas/latest/   301
+# ^           ^                 ^ type of redirect (301 == permanent, 302 or 307 == temporary)
+# |           + path to redirect to
+# + path to redirect (with asterisk wildcard to match all paths starting with that pattern)
+```
+
+Note: UNLIKE the Gatsby redirects shown above, these paths *do* include the `/docs` prefix.
+
+## Consolidating versions
+
+This is similar to the previous example, but concerns a version of documentation that is being eliminated in favor of a more comprehensive version - for example, consolidating all 7.* versions of PEM into one set of Version 7 documentation. Once again, using Frontmatter redirects would result in an unacceptable amount of error-prone work; we'll use [Netlify redirects](../../static/_redirects) here too, but introduce the `:splat` keyword:
+
+```
+/docs/pem/7.12/*  /docs/pem/7/:splat  301
+/docs/pem/7.13/*  /docs/pem/7/:splat  301
+/docs/pem/7.14/*  /docs/pem/7/:splat  301
+/docs/pem/7.15/*  /docs/pem/7/:splat  301
+/docs/pem/7.16/*  /docs/pem/7/:splat  301
+```
+
+As with the EOL'd product version, these rules match all paths starting with the eliminated version prefix (e.g. /docs/pem/7.12), with the asterisk matching the rest of the path. However, instead of redirecting all such requests to the root of the product docs, the path will be rewritten to start with `/docs/pem/7` while preserving the rest! The `:splat` keyword takes whatever the asterisk (also known as a "splat") matches, and includes it in the redirected destination.
+

gatsby-node.js

@@ -219,8 +219,6 @@ exports.createPages = async ({ actions, graphql, reporter }) => {
     // set computed frontmatter
     node.frontmatter = computeFrontmatterForTreeNode(curr);
 
-    configureRedirects(node.fields.path, node.frontmatter.redirects, actions);
-
     // build navigation tree
     const navigationDepth = 2;
     let navRoot = curr;
@@ -231,6 +229,18 @@ exports.createPages = async ({ actions, graphql, reporter }) => {
     const prevNext = findPrevNextNavNodes(navTree, curr);
 
     const { docType } = node.fields;
+
+    const isLatest =
+      docType === "doc"
+        ? productVersions[node.fields.product][0] === node.fields.version
+        : false;
+    configureRedirects(
+      node.fields.path,
+      isLatest,
+      node.frontmatter.redirects,
+      actions,
+    );
+
     if (docType === "doc") {
       createDoc(navTree, prevNext, node, productVersions, actions);
     } else if (docType === "advocacy") {

product_docs/docs/edbcloud/beta/getting_started/01_check_resource_limits.mdx

@@ -8,6 +8,8 @@ The default number of total cores per subscription per region is 20. See [Virtua
 
 The default Public IP address limits for Public IP Addresses Basic and Public IP Addresses Standards is set to 10. See [Public IP address limits](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/azure-subscription-service-limits#publicip-address) for more information. You need to increase the limit of `Public IP Addresses - Basic` and `Public IP Addresses - Standard` for the regions where you plan to deploy your EDB clusters with the total number of EDB clusters you plan to use.
 
+<iframe width="560" height="315" src="https://www.youtube.com/embed/cfl11ajrPhE" title="Video walkthrough of raising Azure resource limits" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+
 ## Virtual Machine Quota Requirements
 In each region, EDB Cloud uses six ESv3 and six DSv2 virtual machine cores to manage your EDB Cloud infrastructure.
 Your Postgres clusters deployed in the region use separate ESv3 virtual machine cores.