From 064ea11a339e2858d937fac44d3d5fbc5d17d134 Mon Sep 17 00:00:00 2001 From: Jody Garnett Date: Thu, 23 May 2024 08:19:24 -0700 Subject: [PATCH 1/6] flatten changelog into current release and release history for ease of maintenance (#7887) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * flatten changelog into current release and release history for ease of maintenance * Deploy instructons with banner when viewing non stable docs * fixup! Deploy instructons with banner when viewing non stable docs * fixup! fixup! Deploy instructons with banner when viewing non stable docs --------- Co-authored-by: Juan Luis Rodríguez # Conflicts: # docs/manual/docs/maintainer-guide/updating/index.md # docs/manual/docs/overview/change-log/history/index.md # docs/manual/docs/overview/change-log/index.md # docs/manual/docs/overview/change-log/maintenance/index.md # docs/manual/mkdocs.yml --- docs/manual/README.md | 22 +++---- .../docs/maintainer-guide/updating/index.md | 5 +- .../change-log/{archive => history}/index.md | 59 +++++++++++++++---- docs/manual/docs/overview/change-log/index.md | 7 +-- .../overview/change-log/maintenance/index.md | 21 ------- .../docs/overview/change-log/stable/index.md | 21 ------- docs/manual/mkdocs.yml | 9 +-- docs/manual/overrides/partials/main.html | 6 ++ 8 files changed, 73 insertions(+), 77 deletions(-) rename docs/manual/docs/overview/change-log/{archive => history}/index.md (71%) delete mode 100644 docs/manual/docs/overview/change-log/maintenance/index.md delete mode 100644 docs/manual/docs/overview/change-log/stable/index.md create mode 100644 docs/manual/overrides/partials/main.html diff --git a/docs/manual/README.md b/docs/manual/README.md index 6a32791b9e9..1aba8def34d 100644 --- a/docs/manual/README.md +++ b/docs/manual/README.md @@ -96,34 +96,36 @@ If you are not familiar with Python the MkDocs-material website has instructions mvn install -Pdefault ``` -## Deploy +## Publish Documentation -We use ``mike`` for publishing to https://geonetwork.github.io using `.` version: +We use ``mike`` for publishing (from the `gh-pages` branch). Docs are published by the ``.github/workflows/docs.yml`` automation each time pull-request is merged. -1. To deploy docs from the `main` branch to website `gh-pages` branch: +If you wish to preview using your own `gh-pages` branch: + +1. To deploy 4.4 docs as latest from the `main` branch to website `gh-pages` branch: ```bash - mike deploy --push --no-redirect --update-aliases 4.4 latest + mike deploy --title "4.4 Latest" --alias-type=copy --update-aliases 4.4 latest ``` - + 2. To deploy documentation for a new release: ```bash - mike deploy --push --no-redirect --update-aliases 4.2 stable + mike deploy --push --alias-type=copy 4.2 stable ``` 3. When starting a new branch you can make it the default: ```bash - mike set-default --push 4.2 + mike set-default --push 4.6 ``` - - Hint: When starting a new branch update `overview/changelog/` navigation tree also. + + Hint: When starting a new branch update `overview/changelog/history/index.md` headings for latest, maintenance, stable (for prior branches also). 4. To publish documentation for a maintenance release: ```bash - mike deploy --push --no-redirect --update-aliases 3.12 maintenance + mike deploy --push --alias-type=copy 3.12 maintenance ``` 5. To show published versions: diff --git a/docs/manual/docs/maintainer-guide/updating/index.md b/docs/manual/docs/maintainer-guide/updating/index.md index d0793a6b0e4..db9e845ed4e 100644 --- a/docs/manual/docs/maintainer-guide/updating/index.md +++ b/docs/manual/docs/maintainer-guide/updating/index.md @@ -81,5 +81,6 @@ Guidance: * For information on new features and functionality: - * [Changelog 4.2.x](../../overview/change-log/stable/index.md) - * [Changelog 4.0.x](../../overview/change-log/archive/index.md#40x) + * [Changelog 4.2](../../overview/change-log/history/index.md#42) + * [Changelog 4.0](../../overview/change-log/history/index.md#40] + diff --git a/docs/manual/docs/overview/change-log/archive/index.md b/docs/manual/docs/overview/change-log/history/index.md similarity index 71% rename from docs/manual/docs/overview/change-log/archive/index.md rename to docs/manual/docs/overview/change-log/history/index.md index 824ca283152..651fdd859e5 100644 --- a/docs/manual/docs/overview/change-log/archive/index.md +++ b/docs/manual/docs/overview/change-log/history/index.md @@ -1,12 +1,45 @@ -# Archived +# Release History -The following series of GeoNetwork are no longer in active use and you are encouraged to migrate to a newer version. - -The GeoNetwork community is not large enough to maintain many active branches of GeoNetwork at one time. Older installations of GeoNetwork may be subject to disclosed security vulnerabilities resulting in our recommendation to update to the supported [stable](../stable/index.md) or [maintenance](../maintenance/index.md) series. +The GeoNetwork community is not large enough to maintain many active branches of GeoNetwork at one time. Older installations of GeoNetwork may be subject to disclosed security vulnerabilities resulting in our recommendation to update to the supported [stable](http://docs.geonetwork-opensource.org/stable/) or [maintenance](https://docs.geonetwork-opensource.org/maintenance/) series if available. Volunteers wishing to backport security fixes to older versions of GeoNetwork are welcome to do so. Commercial support providers are welcome to do so on behalf of their customers. -## 4.0.x +## Stable Release + +The stable release of GeoNetwork is recommended for production use and for new installations of GeoNetwork. + +This series is under active use by our community, with regular improvements, documentation updates, bug reports, fixes, and releases. + +### 4.2 + +- [Version 4.2.9](../version-4.2.9.md) +- [Version 4.2.8](../version-4.2.8.md) +- [Version 4.2.7](../version-4.2.7.md) +- [Version 4.2.6](../version-4.2.6.md) +- [Version 4.2.5](../version-4.2.5.md) +- [Version 4.2.4](../version-4.2.4.md) +- [Version 4.2.3](../version-4.2.3.md) +- [Version 4.2.2](../version-4.2.2.md) +- [Version 4.2.1](../version-4.2.1.md) +- [Version 4.2.0](../version-4.2.0.md) + +## Maintenance Release + +The maintenance release of GeoNetwork provides production systems with essential updates and fixes to allow time to upgrade to the recommended stable release. + +This series is no longer under active development, providing essential fixes, and releases only. + +### No maintenance release + +With the final release of 3.12.12 there is no active maintenance release being provided. + +Production systems are advised to update to 4.2 above if they have not already done so. + +## Archived Releases + +The following series of GeoNetwork are no longer in active use and you are encouraged to migrate to a newer version. + +### 4.0 - [Version 4.0.6](../version-4.0.6.md) - [Version 4.0.5](../version-4.0.5.md) @@ -18,7 +51,7 @@ Volunteers wishing to backport security fixes to older versions of GeoNetwork ar - [Version 4.0.0 Alpha.2](../version-4.0.0-alpha.2.md) - [Version 4.0.0 Alpha.1](../version-4.0.0-alpha.1.md) -## 3.12.x +### 3.12 - [Version 3.12.12](../version-3.12.12.md) - [Version 3.12.11](../version-3.12.11.md) @@ -34,7 +67,7 @@ Volunteers wishing to backport security fixes to older versions of GeoNetwork ar - [Version 3.12.1](../version-3.12.1.md) - [Version 3.12.0](../version-3.12.0.md) -## 3.10.x +### 3.10 - [Version 3.10.10](../version-3.10.10.md) - [Version 3.10.9](../version-3.10.9.md) @@ -66,18 +99,18 @@ Volunteers wishing to backport security fixes to older versions of GeoNetwork ar - [Version 3.0.1](../version-3.0.1.md) - [Version 3.0.0](../version-3.0.0.md) -## 3.8.x +### 3.8 - [Version 3.8.3](../version-3.8.3.md) - [Version 3.8.2](../version-3.8.2.md) - [Version 3.8.1](../version-3.8.1.md) - [Version 3.8.0](../version-3.8.0.md) -## 3.6.x +### 3.6 - [Version 3.6.0](../version-3.6.0.md) -## 3.4.x +### 3.4 - [Version 3.4.4](../version-3.4.4.md) - [Version 3.4.3](../version-3.4.3.md) @@ -85,13 +118,13 @@ Volunteers wishing to backport security fixes to older versions of GeoNetwork ar - [Version 3.4.1](../version-3.4.1.md) - [Version 3.4.0](../version-3.4.0.md) -## 3.2.x +### 3.2 - [Version 3.2.2](../version-3.2.2.md) - [Version 3.2.1](../version-3.2.1.md) - [Version 3.2.0](../version-3.2.0.md) -## 3.0.x +### 3.0 - [Version 3.0.4](../version-3.0.4.md) - [Version 3.0.3](../version-3.0.3.md) @@ -99,7 +132,7 @@ Volunteers wishing to backport security fixes to older versions of GeoNetwork ar - [Version 3.0.1](../version-3.0.1.md) - [Version 3.0.0](../version-3.0.0.md) -## 2.10.x +### 2.10 All development has ceased: diff --git a/docs/manual/docs/overview/change-log/index.md b/docs/manual/docs/overview/change-log/index.md index cf1072c0de7..57c190a63df 100644 --- a/docs/manual/docs/overview/change-log/index.md +++ b/docs/manual/docs/overview/change-log/index.md @@ -1,7 +1,6 @@ # Change log -Notable changes made to a GeoNetwork-open source including new features, migration instructions, and bug fixes. +Notable changes made to GeoNetwork opensource including new features, migration instructions, and bug fixes. -- [Stable](stable/index.md) -- [Maintenance](maintenance/index.md) -- [Archive](archive/index.md) +- [Version 4.2.9](version-4.2.9.md) +- [Release History](history/index.md) diff --git a/docs/manual/docs/overview/change-log/maintenance/index.md b/docs/manual/docs/overview/change-log/maintenance/index.md deleted file mode 100644 index e1cabe39f53..00000000000 --- a/docs/manual/docs/overview/change-log/maintenance/index.md +++ /dev/null @@ -1,21 +0,0 @@ -# Maintenance - -The GeoNetwork 4.2.x series has entered maintenance for continued support production systems. - -This series is under active use by our community, with regular improvements, documentation updates, bug reports, fixes, and releases. - -## Latest - -- [Version 4.2.9](../version-4.2.9.md) - -## History - -- [Version 4.2.8](../version-4.2.8.md) -- [Version 4.2.7](../version-4.2.7.md) -- [Version 4.2.6](../version-4.2.6.md) -- [Version 4.2.5](../version-4.2.5.md) -- [Version 4.2.4](../version-4.2.4.md) -- [Version 4.2.3](../version-4.2.3.md) -- [Version 4.2.2](../version-4.2.2.md) -- [Version 4.2.1](../version-4.2.1.md) -- [Version 4.2.0](../version-4.2.0.md) diff --git a/docs/manual/docs/overview/change-log/stable/index.md b/docs/manual/docs/overview/change-log/stable/index.md deleted file mode 100644 index ad5d4b53c6f..00000000000 --- a/docs/manual/docs/overview/change-log/stable/index.md +++ /dev/null @@ -1,21 +0,0 @@ -# Stable - -The GeoNetwork 4.2.x series is stable and recommended for production use and new installations of GeoNetwork. -This series is under active use by our community, with regular improvements, documentation updates, bug reports, fixes, and releases. - -## Latest - -- [Version 4.2.9](../version-4.2.9.md) - - -## History - -- [Version 4.2.8](../version-4.2.8.md) -- [Version 4.2.7](../version-4.2.7.md) -- [Version 4.2.6](../version-4.2.6.md) -- [Version 4.2.5](../version-4.2.5.md) -- [Version 4.2.4](../version-4.2.4.md) -- [Version 4.2.3](../version-4.2.3.md) -- [Version 4.2.2](../version-4.2.2.md) -- [Version 4.2.1](../version-4.2.1.md) -- [Version 4.2.0](../version-4.2.0.md) diff --git a/docs/manual/mkdocs.yml b/docs/manual/mkdocs.yml index d25163ec3e4..8fc9050f89b 100644 --- a/docs/manual/mkdocs.yml +++ b/docs/manual/mkdocs.yml @@ -147,9 +147,9 @@ nav: - overview/authors.md - 'Changelog': - overview/change-log/index.md - - 'Stable': - - overview/change-log/stable/index.md - - overview/change-log/version-4.2.9.md + - overview/change-log/version-4.2.9.md + - 'Release History': + - overview/change-log/history/index.md - overview/change-log/version-4.2.8.md - overview/change-log/version-4.2.7.md - overview/change-log/version-4.2.6.md @@ -159,8 +159,6 @@ nav: - overview/change-log/version-4.2.2.md - overview/change-log/version-4.2.1.md - overview/change-log/version-4.2.0.md - - 'Archive': - - overview/change-log/archive/index.md - overview/change-log/version-3.12.12.md - overview/change-log/version-3.12.11.md - overview/change-log/version-3.12.10.md @@ -174,7 +172,6 @@ nav: - overview/change-log/version-3.12.2.md - overview/change-log/version-3.12.1.md - overview/change-log/version-3.12.0.md - - overview/change-log/archive/index.md - overview/change-log/version-4.0.6.md - overview/change-log/version-4.0.5.md - overview/change-log/version-4.0.4.md diff --git a/docs/manual/overrides/partials/main.html b/docs/manual/overrides/partials/main.html new file mode 100644 index 00000000000..beda7eade16 --- /dev/null +++ b/docs/manual/overrides/partials/main.html @@ -0,0 +1,6 @@ +{% extends "base.html" %} + +{% block outdated %} + GeoNetwork 4.2 is outdated. + Click here to go to stable. +{% endblock %} From 8538e22e4cf7c82ff53c8486d2d037cde278bbeb Mon Sep 17 00:00:00 2001 From: Jody Garnett Date: Thu, 23 May 2024 11:14:38 -0700 Subject: [PATCH 2/6] how to update mkdoc env (removed instructions for docker mkdocs use) --- docs/manual/README.md | 29 ++++++++++++++++++++--------- 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/docs/manual/README.md b/docs/manual/README.md index 1aba8def34d..0df21e4d88c 100644 --- a/docs/manual/README.md +++ b/docs/manual/README.md @@ -23,6 +23,12 @@ If you are using Python3: ```bash pip3 install -r requirements.txt ``` + + In the future you can update using: + + ```bash + pip3 install -r requirements.txt -U + ``` 2. Use ***mkdocs** to preview locally: @@ -55,6 +61,13 @@ If you use a Python virtual environment: pip install -r requirements.txt ``` + In the future you can update with: + + ```bash + source venv/bin/activate + pip3 install -r requirements.txt + ``` + 2. Use ***mkdocs*** to preview from virtual environment: ```bash @@ -63,18 +76,16 @@ If you use a Python virtual environment: 3. Preview: http://localhost:8000 -### Docker - -If you are not familiar with Python the MkDocs-material website has instructions for Docker: - -1. Run MkDocs in Docker environment: - + Preview uses a single version, so expect some warnings from version chooser: ``` - docker pull squidfunk/mkdocs-material - docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material + "GET /versions.json HTTP/1.1" code 404 ``` + +4. Optional: Preview online help: -2. Preview: http://localhost:8000 + ```bash + mkdocs serve --config-file help.yml + ``` ## Maven Integration From 61c7cff33468dc0910e433db0f8709916e57dd82 Mon Sep 17 00:00:00 2001 From: Jody Garnett Date: Thu, 23 May 2024 12:03:39 -0700 Subject: [PATCH 3/6] maintenance release description, fix broken link on change-log/history for stable and maintenance headings # Conflicts: # docs/manual/docs/overview/change-log/history/index.md --- docs/manual/docs/overview/change-log/history/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/manual/docs/overview/change-log/history/index.md b/docs/manual/docs/overview/change-log/history/index.md index 651fdd859e5..cc9653abd2c 100644 --- a/docs/manual/docs/overview/change-log/history/index.md +++ b/docs/manual/docs/overview/change-log/history/index.md @@ -8,7 +8,7 @@ Volunteers wishing to backport security fixes to older versions of GeoNetwork ar The stable release of GeoNetwork is recommended for production use and for new installations of GeoNetwork. -This series is under active use by our community, with regular improvements, documentation updates, bug reports, fixes, and releases. +This series is under **active use** by our community, with regular improvements, documentation updates, bug reports, fixes, and releases. ### 4.2 @@ -27,7 +27,7 @@ This series is under active use by our community, with regular improvements, doc The maintenance release of GeoNetwork provides production systems with essential updates and fixes to allow time to upgrade to the recommended stable release. -This series is no longer under active development, providing essential fixes, and releases only. +When available the maintenace series provides **time to upgrade** for our community - limited to providing essential fixes only. ### No maintenance release From 6db9d710191e3bf8da3109f93bc520ef90dab048 Mon Sep 17 00:00:00 2001 From: Jody Garnett Date: Fri, 24 May 2024 12:40:06 -0700 Subject: [PATCH 4/6] fix documentation warnings --- docs/manual/docs/help/record/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/manual/docs/help/record/index.md b/docs/manual/docs/help/record/index.md index 7b7b9c58a7a..df3b8cd7e52 100644 --- a/docs/manual/docs/help/record/index.md +++ b/docs/manual/docs/help/record/index.md @@ -194,7 +194,7 @@ Download the contents of a single record. - A folder containing complete **`metadata.xml`** record, and simplified ***`metadata-iso19139.xml`*** record. - ***`index.html`** and **`index.csv`** summary described in - the [previous section](#download-from-search-results). + the [previous section](../search/index.md#download-from-search-results). ![](img/export_record_zip.png) *Export (ZIP) index.html summary* From fde7191f4ce6fdb693d44568f13abc87bbe6f648 Mon Sep 17 00:00:00 2001 From: Jody Garnett Date: Fri, 24 May 2024 12:40:59 -0700 Subject: [PATCH 5/6] reduce instructions to what is useful for the 4.2 branch --- docs/manual/README.md | 26 +++----------------------- 1 file changed, 3 insertions(+), 23 deletions(-) diff --git a/docs/manual/README.md b/docs/manual/README.md index 0df21e4d88c..6ad8be436f7 100644 --- a/docs/manual/README.md +++ b/docs/manual/README.md @@ -113,40 +113,20 @@ We use ``mike`` for publishing (from the `gh-pages` branch). Docs are published If you wish to preview using your own `gh-pages` branch: -1. To deploy 4.4 docs as latest from the `main` branch to website `gh-pages` branch: - - ```bash - mike deploy --title "4.4 Latest" --alias-type=copy --update-aliases 4.4 latest - ``` - -2. To deploy documentation for a new release: +1. To deploy documentation for a new stable release: ```bash mike deploy --push --alias-type=copy 4.2 stable ``` -3. When starting a new branch you can make it the default: - - ```bash - mike set-default --push 4.6 - ``` - - Hint: When starting a new branch update `overview/changelog/history/index.md` headings for latest, maintenance, stable (for prior branches also). - -4. To publish documentation for a maintenance release: - - ```bash - mike deploy --push --alias-type=copy 3.12 maintenance - ``` - -5. To show published versions: +2. To show published versions: ```bash mike list ``` -6. To preview things locally (uses your local ``gh-pages`` branch): +3. To preview things locally (uses your local ``gh-pages`` branch): ```bash mike serve From 98832c15422f62794dbe1d9dd5df9bb6282f3b9d Mon Sep 17 00:00:00 2001 From: Jody Garnett Date: Fri, 24 May 2024 15:01:26 -0700 Subject: [PATCH 6/6] outdated banner --- docs/manual/overrides/{partials => }/main.html | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/manual/overrides/{partials => }/main.html (100%) diff --git a/docs/manual/overrides/partials/main.html b/docs/manual/overrides/main.html similarity index 100% rename from docs/manual/overrides/partials/main.html rename to docs/manual/overrides/main.html