add clarification on use of HTTP status codes for GC Technical considerations (#230)

.github/workflows/gdc-all-channels.yml

@@ -2,7 +2,8 @@ name: Generate list of all GDC channels
 
 on:
   schedule:
-    - cron: '0 * * * *'  # runs every hour
+    - cron: '0/15 * * * *'  # runs every 15 minutes
+    # - cron: '0 * * * *'  # runs every hour
     # - cron: '* * * * *'  # runs every minute, for debugging
 
 env:

.github/workflows/guide-infcom.yml

@@ -0,0 +1,47 @@
+name: WIS2 Guide for INFCOM review
+
+on:
+  push:
+    branches:
+    - INFCOM-4
+
+env:
+  FILE_BASENAME: wis2-guide-DRAFT-INFCOM-4
+
+jobs:
+  build-wis2-guide:
+    name: Generate documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install dependencies
+        run: |
+          sudo apt-get update -y \
+          && sudo apt-get install -y pandoc \
+          && sudo gem install asciidoctor asciidoctor-pdf
+      - name: checkout repository
+        uses: actions/checkout@master
+      - name: build documentation
+        run: |
+          mkdir -p /tmp/wis2-guide/guide/images \
+          && cd guide \
+          && asciidoctor --trace -a stylesheet=css/wmo-asciidoc.css -o /tmp/wis2-guide/guide/${FILE_BASENAME}.html index.adoc \
+          && asciidoctor --trace --backend docbook --out-file - index.adoc | pandoc --from docbook --to docx --output /tmp/wis2-guide/guide/${FILE_BASENAME}.docx \
+          && asciidoctor --trace -r asciidoctor-pdf --trace -b pdf -o /tmp/wis2-guide/guide/${FILE_BASENAME}.pdf index.adoc \
+          && cp images/*.png /tmp/wis2-guide/guide/images \
+          && cd ..
+      - name: checkout gh-pages branch
+        uses: actions/checkout@master
+        with:
+          ref: gh-pages
+      - name: update gh-pages branch and publish
+        run: | 
+          git checkout gh-pages
+          git config --global user.email "tomkralidis@gmail.com"
+          git config --global user.name "Tom Kralidis"
+          rm -rf guide/infcom
+          mkdir -p guide/infcom
+          mv -f /tmp/wis2-guide/* guide/infcom
+          git add .
+          git commit -am "update WIS2 Guide INFCOM build"
+          git push
+

.github/workflows/guide.yml

@@ -19,18 +19,18 @@ jobs:
           && sudo apt-get install -y pandoc \
           && sudo gem install asciidoctor asciidoctor-pdf
       - name: checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@master
       - name: build documentation
         run: |
           mkdir -p /tmp/wis2-guide/guide/images \
           && cd guide \
-          && asciidoctor --trace -o /tmp/wis2-guide/guide/${FILE_BASENAME}.html index.adoc \
+          && asciidoctor --trace -a stylesheet=css/wmo-asciidoc.css -o /tmp/wis2-guide/guide/${FILE_BASENAME}.html index.adoc \
           && asciidoctor --trace --backend docbook --out-file - index.adoc | pandoc --from docbook --to docx --output /tmp/wis2-guide/guide/${FILE_BASENAME}.docx \
           && asciidoctor --trace -r asciidoctor-pdf --trace -b pdf -o /tmp/wis2-guide/guide/${FILE_BASENAME}.pdf index.adoc \
           && cp images/*.png /tmp/wis2-guide/guide/images \
           && cd ..
       - name: checkout gh-pages branch
-        uses: actions/checkout@v3
+        uses: actions/checkout@master
         with:
           ref: gh-pages
       - name: update gh-pages branch and publish

.github/workflows/test-guide-infcom.yml

@@ -0,0 +1,31 @@
+name: Test WIS2 Guide build for INFCOM review
+
+on:
+  pull_request:
+    branches:
+      - INFCOM-4
+    paths:
+      - '**.adoc'
+
+env:
+  FILE_BASENAME: wis2-guide-DRAFT-INFCOM-4
+
+jobs:
+  build-wis2-guide:
+    name: Test documentation build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install dependencies
+        run: |
+          sudo apt-get update -y \
+          && sudo apt-get install -y pandoc \
+          && sudo gem install asciidoctor asciidoctor-pdf
+      - name: checkout repository
+        uses: actions/checkout@master
+      - name: build documentation
+        run: |
+          mkdir -p /tmp/wis2-guide/guide/images \
+          && cd guide \
+          && asciidoctor --trace -a stylesheet=css/wmo-asciidoc.css -o /tmp/wis2-guide/guide/${FILE_BASENAME}.html index.adoc \
+          && asciidoctor --trace --backend docbook --out-file - index.adoc | pandoc --from docbook --to docx --output /tmp/wis2-guide/guide/${FILE_BASENAME}.docx \
+          && asciidoctor --trace -r asciidoctor-pdf --trace -b pdf -o /tmp/wis2-guide/guide/${FILE_BASENAME}.pdf index.adoc

.github/workflows/test-guide.yml

@@ -3,7 +3,7 @@ name: Test WIS2 Guide build
 on:
   pull_request:
     paths:
-      - '**.adoc'   
+      - '**.adoc'
 
 env:
   FILE_BASENAME: wis2-guide-APPROVED
@@ -19,11 +19,11 @@ jobs:
           && sudo apt-get install -y pandoc \
           && sudo gem install asciidoctor asciidoctor-pdf
       - name: checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@master
       - name: build documentation
         run: |
           mkdir -p /tmp/wis2-guide/guide/images \
           && cd guide \
-          && asciidoctor --trace -o /tmp/wis2-guide/guide/${FILE_BASENAME}.html index.adoc \
+          && asciidoctor --trace -a stylesheet=css/wmo-asciidoc.css -o /tmp/wis2-guide/guide/${FILE_BASENAME}.html index.adoc \
           && asciidoctor --trace --backend docbook --out-file - index.adoc | pandoc --from docbook --to docx --output /tmp/wis2-guide/guide/${FILE_BASENAME}.docx \
           && asciidoctor --trace -r asciidoctor-pdf --trace -b pdf -o /tmp/wis2-guide/guide/${FILE_BASENAME}.pdf index.adoc

guide/Makefile

@@ -1,7 +1,7 @@
 FILE_BASENAME=wis2-guide-APPROVED
 
 html:
-	asciidoctor --trace -o ${FILE_BASENAME}.html index.adoc
+	asciidoctor --trace -a stylesheet=css/wmo-asciidoc.css -o ${FILE_BASENAME}.html index.adoc
 
 pdf:
 	asciidoctor --trace -r asciidoctor-pdf --trace -b pdf -o ${FILE_BASENAME}.pdf index.adoc

guide/README.md

@@ -27,10 +27,7 @@ asciidoctor --trace -o wis2-guide.html index.adoc
 asciidoctor --trace -r asciidoctor-pdf --trace -b pdf -o wis2-guide.pdf index.adoc
 # create Word document
 asciidoctor --trace --backend docbook --out-file - index.adoc | pandoc --from docbook --to docx --output wis2-guide.docx
-```
-
 # check links
-```bash
 find . -name "???.adoc" -exec asciidoc-link-check -p -c asciidoc-link-check-config.json {} \;
 ```
 

guide/css/wmo-asciidoc.css

@@ -0,0 +1,65 @@
+@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700";
+@import "https://cdn.jsdelivr.net/gh/asciidoctor/asciidoctor@2.0/data/stylesheets/asciidoctor-default.css";
+
+h1, h2, h3, h4, h5, h6,
+.sidebarblock > .content > .title {
+  color: #005398;
+  font-weight: bold;
+}
+
+#toctitle {
+  color: #005398;
+  font-weight: bold;
+}
+
+#content #toc {
+    border: 1px solid #005398;
+    margin-bottom: 1.25em;
+    padding: 1.25em;
+    background: #ffffff;
+    border-radius: 4px;
+}
+
+#header {
+  border-bottom: 4px solid #005398;
+  margin-top: 10px;
+
+}
+
+#header>h1:first-child {
+    color: #005398;
+    margin-top: 15px;
+    margin-bottom: 0;
+}
+
+#header::before {
+  content: "";
+  display: block;
+  height: 72px;
+  background: url("images/wmo-logo-en.png") no-repeat left center;
+  background-size: contain;
+}
+
+body {
+  font-family: "Montserrat", sans-serif;
+}
+
+.subheader, .admonitionblock td.content>.title, .audioblock>.title, .exampleblock>.title, .imageblock>.title, .listingblock>.title, .literalblock>.title, .stemblock>.title, .openblock>.title, .paragraph>.title, .quoteblock>.title, table.tableblock>.title, .verseblock>.title, .videoblock>.title, .dlist>.title, .olist>.title, .ulist>.title, .qlist>.title, .hdlist>.title {
+    line-height: 1.45;
+    color: #005398;
+    font-weight: 400;
+    margin-top: 0;
+    margin-bottom: .25em;
+}
+
+#footer {
+    max-width: none;
+    background: #005398;
+    padding: 1.25em;
+}
+
+#footer-text {
+    color: #ffffff;
+    line-height: 1.44;
+    font-weight: bold;
+}

guide/index.adoc

@@ -1,8 +1,8 @@
-:title: Guide to the WMO Information System Volume II (APPROVED) - WMO Information System 2.0
+:title: Guide to the WMO Information System (WMO-No. 1061), Volume II - WMO Information System 2.0 (APPROVED)
 :titletext: {title}
-:version: 1.0.0
-:date: {docdate}
-:copyright: Copyright © 2024 World Meteorological Organization (WMO)
+:version: 1.2.0
+:date: 2026-02-02
+:copyright: Copyright © 2026 World Meteorological Organization (WMO)
 :doctype: book
 :encoding: utf-8
 :lang: en
@@ -17,7 +17,7 @@
 |===
 |{set:cellbgcolor:#FFFFFF}
 |[big]*World Meteorological Organization*
-|Date: {date}
+|Date: 2026-02-02
 |Version: {version}
 |Document status: APPROVED
 |Document location: https://wmo-im.github.io/wis2-guide/guide/wis2-guide-APPROVED.html
@@ -42,6 +42,8 @@ include::sections/part4/index.adoc[]
 
 include::sections/part5/index.adoc[]
 
+include::sections/annex_a.adoc[]
+
 
 
 // include::sections/other-considerations.adoc[]

guide/sections/annex_a.adoc

@@ -0,0 +1,11 @@
+[appendix]
+:appendix-caption: Annex
+== Revision History
+
+[cols="12,18,12,12,46",options="header"]
+|===
+|Date |Release |Proposed by | Primary clauses modified |Approved by
+|June 2024| 1.0.0 | SC-IMT | Initial approval for publication| EC-78
+|November 2024 | 1.1.0 | SC-IMT |https://github.com/wmo-im/wis2-guide/milestone/3?closed=1[See GitHub]| Fast-track 2024-2
+|February 2026 | 1.2.0 | SC-IMT |https://github.com/wmo-im/wis2-guide/milestone/7?closed=1[See GitHub] |Fast-track 2025-2
+|===

guide/sections/part1/data-consumer.adoc

@@ -12,7 +12,7 @@ The Global Discovery Catalogue is accessible via an API and provides a low-barri
 
 ==== 1.2.2 How to subscribe to notifications about the availability of new data
 
-WIS2 provides notifications about updates to datasets, for example, a notification may indicate that a new observation record from an automatic weather station has been added to a dataset of surface observations. These notifications are published on Message Brokers. Where data consumers need to use data rapidly once they have been published (for example, as inputs to a weather prediction model), they should subscribe to one or more Global Brokers to get notification messages using Message Queuing Telemetry Transport (MQTT) protocol.footnote[Subscribing to notifications about newly available data ensures that the data consumers do not need to continually to poll the data server to check for updates.]
+WIS2 provides notifications about updates to datasets, for example, a notification may indicate that a new observation record from an automatic weather station has been added to a dataset of surface observations. These notifications are published on Message Brokers. Where data consumers need to use data rapidly once they have been published (for example, as inputs to a weather prediction model), they should subscribe to one or more Global Brokers to get notification messages using Message Queuing Telemetry Transport (MQTT) protocol.footnote:[Subscribing to notifications about newly available data ensures that the data consumers do not need to continually to poll the data server to check for updates.]
 
 In WIS2, notifications are republished by Global Brokers to ensure resilient distribution. Consequently, there will be multiple places where one can subscribe. Data consumers requiring real-time notifications must subscribe to Global Brokers. Data consumers should subscribe to more than one Global Broker to ensure that notifications continue to be received if a Global Broker instance fails.
 

guide/sections/part1/data-publisher.adoc

@@ -27,16 +27,18 @@ Copies of all discovery metadata records from WIS2 are held in the Global Discov
 Depending on local arrangements, your GISC may be able to assist in transferring discovery metadata record(s) to the Global Discovery Catalogues. If this is not the case, data publishers will need to publish the discovery metadata record(s) themselvesfootnote:[In the future, WIS2 may provide metadata publication services (for example, through a WIS2 metadata management portal) to assist with this task. However, such services are not currently available.] using one of two methods:
 
 * The simplest method is to encode the discovery metadata record as a file and publish it to an HTTP server, where it can be accessed with a URL. 
-* Alternatively, a data publisher may operate a local metadata catalogue through which discovery metadata records can be shared using an API (for example, OGC API – Recordsfootnote:[See OGC API - Records - Part 1: Core: https://docs.ogc.org/DRAFTS/20-004.html.]). Each discovery metadata record (for instance, an item that is part of the discovery metadata catalogue) can be accessed with a unique URL via the API .
+* Alternatively, a data publisher may operate a local metadata catalogue through which discovery metadata records can be shared using an API (for example, OGC API – Records). Each discovery metadata record (for instance, an item that is part of the discovery metadata catalogue) can be accessed with a unique URL via the API.
 
-In both cases, a notification message needs to be published on a Message Broker that tells WIS2 that there is a new discovery metadata record to upload and that it can be accessed at the specified URL.footnote:[Both data and metadata are published using the same notification message mechanism to announce the availability of new resources.] Notification messages shall conform to the specification given in the _Manual on WIS_, Volume II - Appendix E. WIS2 Notification Message. They must also be published on a topic that conforms to the specification given in the _Manual on WIS_, Volume II - Appendix D. WIS2 Topic Hierarchy. For example, metadata published by Deutscher Wetterdienst would use the following topic: ``origin/a/wis2/de-dwd/metadata/core``.
+In both cases, a notification message needs to be published on a Message Broker that tells WIS2 that there is a new discovery metadata record to upload and that it can be accessed at the specified URL.footnote:[Both data and metadata are published using the same notification message mechanism to announce the availability of new resources.] Notification messages shall conform to the specification given in the _Manual on WIS_, Volume II - Appendix E. WIS2 Notification Message. They must also be published on a topic that conforms to the specification given in the _Manual on WIS_, Volume II - Appendix D. WIS2 Topic Hierarchy. For example, metadata published by Deutscher Wetterdienst would use the following topic: ``origin/a/wis2/de-dwd/metadata``.
 
 These discovery metadata records are then propagated through the Global Service components into the Global Discovery Catalogue, where data consumers can search and browse for datasets of interest.
 
 Upon receipt of a new discovery metadata record, a Global Discovery Catalogue (see <<_2_4_4_global_discovery_catalogue>>) will validate, assess, ingest, and publish the record. Validation ensures compliance with the specification, while the assessment evaluates the discovery record against good practices. The Global Discovery Catalogue will notify the data publisher if the discovery metadata record fails validation and provide recommendations for improvements. 
 
 Discovery metadata must be published in the Global Discovery Catalogues before the data are published.
 
+Discovery metadata should be re-published on a daily basis.
+
 ==== 1.3.3 How to provide data to WIS2
 
 WIS2 is based on the web architecture.footnote:[See Architecture of the World Wide Web, Volume One: https://www.w3.org/TR/webarch/.] As such it is _resource oriented_. Datasets are resources; the "granules" of data grouped in a dataset are resources; and the discovery metadata records that describe datasets are resources. In web architecture, every resource has a unique identifier (such as a URIfootnote:[See RFC 3986 - Uniform Resource Identifier (URI) - Generic Syntax: https://datatracker.ietf.org/doc/html/rfc3986.]), which can be used to resolve the identified resource and interact with it (for example, to download a representation of the resource over an open-standard protocol such as HTTP).