build: Expand versioning process in readme

README.md

@@ -19,13 +19,43 @@ In order to render and preview the site locally (without docker) you will need a
 
 ## "Publishing" your changes
 
-Publishing is now done by the jenkins pipeline. Once a PR is merged to master, the changes will be reflected on the documentation site. 
+Publishing is done by the jenkins pipeline. Once a PR is merged, the changes will be reflected on the documentation site, hosted under [gh-pages] branch and served by Github Pages.
+
+The different versions of the documentation are maintained in separate branches.
+The `main` branch hosts the source files for the version that is under development as well as the following **production site files**:
+- `docs/CNAME` - DNS record which tells Github Pages to serve the content at https://docs.edgexfoundry.org instead of https://edgexfoundry.github.io/edgex-docs
+- `docs/index.html` - site index page that redirects from `/` to `/{latest-release}`
+- `docs/versions.json` - version info to populate the site version drop-down menu
+- `versions.json` - identical to `docs/versions.json`. Unknown purpose!
+
+The pipeline copies the files to separate directories inside [gh-pages] branch. 
+For example, when the dev version is 2.2:
+
+| Source                  | Production             |
+|-------------------------|------------------------|
+| main/docs/CNAME         | gh-pages/CNAME         |
+| main/docs/index.html    | gh-pages/index.html    |
+| main/docs/versions.json | gh-pages/versions.json |
+| main/docs_src/*         | gh-pages/2.2/*         |
+| jakarta/docs_src/*      | gh-pages/2.1/*         |
+| ireland/docs_src/*      | gh-pages/2.0/*         |
+
+Other files such as for CI checks and guidelines are also copied from all branches.
 
 ## Versioning the docs
 
-When a new version of EdgeX is released, we version the docs as well. There are three steps to make this happen:
+When a new version of EdgeX is released, we version the docs as well. There are four steps to make this happen:
 
-1) Add the version to be added to the `versions.json` file. This file will populate the drop down in the site deployed at https://docs.edgexfoundry.org 
+1) Create a branch without production site files
+
+    i) Create a branch from `main` for the released documentation
+    The branch name should be the new EdgeX release name.
+    For example, for 2.2, a `kamakura` branch is created.
+
+    ii) Remove **production site files** from the branch, listed [here](#publishing-your-changes).
+    This is necessary to avoid overriding production files; see [#680](https://github.com/edgexfoundry/edgex-docs/issues/680).
+
+2) Add the version to be added to the `docs/versions.json` file. This file will populate the drop down in the site deployed at https://docs.edgexfoundry.org 
 ``` json
 [
     {"version": "1.1", "title": "1.1-Fuji", "aliases": []},
@@ -34,7 +64,7 @@ When a new version of EdgeX is released, we version the docs as well. There are
 ]
 ```
 
-2) The value placed in `version` property in the json above *MUST* match the name of the folder that contains the versioned content in the `gh-pages` branch. This is specified by updating the `site_dir:` property in the `mkdocs.yml` file:
+3) The value placed in `version` property in the json above *MUST* match the name of the folder that contains the versioned content in the [gh-pages] branch. This is specified by updating the `site_dir:` property in the `mkdocs.yml` file:
 ``` yaml
 site_name: EdgeX Foundry Documentation
 docs_dir: ./docs_src
@@ -49,17 +79,16 @@ copyright: 'Copyright © 2020 EdgeX Foundry'
 ```
 Once this is done and merged, the build job will place content in the specified folder in the gh-pages branch. 
 
-3) The last step, once everything is in place, is to update the site. The docs site is a statically hosted site on github pages from the `gh-pages` branch. Normally we leave this branch alone as the build job will take care of updating it. However, versioning is a bit different.You'll need to do TWO things.  Ideally this would be automated, but it is manual for now given it happens once per release.
-    1. You'll need to repeat step 1 against the `gh-pages` branch. Think of it as master is dev and `gh-pages` is prod.
-    2. You'll need to update the `index.html` to redirect users to the current version: 
+4) Update the `docs/index.html` to redirect from `/` to the most recent release directory.
+For example, if the latest release is `2.1`:
 
 ``` html
 <!DOCTYPE html>
 <html>
 <head>
 <title>Redirecting</title>
 <script>
-    window.location.replace("1.2"); //UPDATE ME
+    window.location.replace("2.1"); //UPDATE ME
 </script>
 </head>
 <body>
@@ -68,4 +97,4 @@ Once this is done and merged, the build job will place content in the specified
 ```
 
 
-
+ [gh-pages]: https://github.com/edgexfoundry/edgex-docs/tree/gh-pages