From 7098f3346b307006a8e4009aff0838713e43fa41 Mon Sep 17 00:00:00 2001 From: Farshid Tavakolizadeh Date: Tue, 22 Feb 2022 12:43:58 +0100 Subject: [PATCH 1/2] build: Expand versioning process in readme Signed-off-by: Farshid Tavakolizadeh --- README.md | 47 ++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 38 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 07a235d0ee..9c0f133cf4 100644 --- a/README.md +++ b/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,9 +79,8 @@ 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 @@ -59,7 +88,7 @@ Once this is done and merged, the build job will place content in the specified Redirecting @@ -68,4 +97,4 @@ Once this is done and merged, the build job will place content in the specified ``` - \ No newline at end of file + [gh-pages]: https://github.com/edgexfoundry/edgex-docs/tree/gh-pages \ No newline at end of file From 512d9bb09f78c197b0b55462894954b235e43abd Mon Sep 17 00:00:00 2001 From: Farshid Tavakolizadeh Date: Wed, 23 Feb 2022 17:00:12 +0100 Subject: [PATCH 2/2] fix: remove redundant version file The reference version file is at docs/versions.json Signed-off-by: Farshid Tavakolizadeh --- README.md | 1 - versions.json | 8 -------- 2 files changed, 9 deletions(-) delete mode 100644 versions.json diff --git a/README.md b/README.md index 9c0f133cf4..3aff3694ca 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,6 @@ The `main` branch hosts the source files for the version that is under developme - `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: diff --git a/versions.json b/versions.json deleted file mode 100644 index e78102e3a7..0000000000 --- a/versions.json +++ /dev/null @@ -1,8 +0,0 @@ -[ - {"version": "1.1", "title": "1.1-Fuji", "aliases": []}, - {"version": "1.2", "title": "1.2-Geneva", "aliases": []}, - {"version": "1.3", "title": "1.3-Hanoi", "aliases": []}, - {"version": "2.0", "title": "2.0-Ireland", "aliases": []}, - {"version": "2.1", "title": "2.1-Jakarta", "aliases": []}, - {"version": "2.2", "title": "2.2-Kamakura", "aliases": []} -] \ No newline at end of file