[i18n] Support automatic banner management across localizations (#4625)

.github/workflows/check-i18n.yml

@@ -9,5 +9,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # all
       - run: scripts/i18n-check.sh -u
       - run: .github/workflows/scripts/i18n-check-helper.sh

archetypes/announcement.md

@@ -0,0 +1,10 @@
+---
+title: {{ replaceRE "[-_]" " " .Name | title }}
+date: {{ .Date | time.Format "2006-01-02" }} # Start date (optional)
+expiryDate: {{ dateFormat "2006-01-02" .Date }} # End date (optional)
+---
+
+<!-- For more detail about announcements, see
+https://opentelemetry.io/docs/contributing/#announcement-management
+
+Erase this comment once you are done including the announcement text below. -->

content/en/_index.md

@@ -10,18 +10,6 @@ developer_note:
   The blocks/cover shortcode (used below) will use as a background image any
   image file containing "background" in its name.
 show_banner: true
-limit_banner: 2 # Default to 2, adjust as needed
-banners:
-  - message:
-      '<i class="fas fa-bullhorn"></i> We are happy to announce that Elastic''s
-      donation of the [**eBPF profiling agent has been
-      accepted**](/blog/2024/elastic-contributes-continuous-profiling-agent)!'
-    to: 2024-07-25
-  - message:
-      '<i class="fas fa-bullhorn"></i> Join us for [**OTel Community Day** on
-      June
-      25th](https://events.linuxfoundation.org/open-telemetry-community-day/)!'
-    to: 2024-06-25
 ---
 
 <div class="d-none"><a rel="me" href="https://fosstodon.org/@opentelemetry"></a></div>

content/en/announcements/_index.md

@@ -0,0 +1,5 @@
+---
+title: Announcements
+cascade:
+  type: docs
+---

content/en/announcements/eBPF.md

@@ -0,0 +1,8 @@
+---
+title: eBPF
+date: 2024-06-07
+expiryDate: 2024-07-25
+---
+
+Elastic's **eBPF profiling agent** is now part of OTel.
+[Learn more](/blog/2024/elastic-contributes-continuous-profiling-agent)

content/en/announcements/otel-community-day.md

@@ -0,0 +1,10 @@
+---
+title: OTel Community Day
+date: 2024-04-05
+expiryDate: 2024-06-25
+weight: -1 # top
+---
+
+<i class="fas fa-bullhorn"></i> Join us for
+[**OTel Community Day**](https://events.linuxfoundation.org/open-telemetry-community-day/)
+on June 25th

content/en/docs/contributing/_index.md

@@ -600,6 +600,53 @@ Keep the following in mind when filing an issue:
   Respect your fellow contributors. For example, "The docs are terrible" is not
   helpful or polite feedback.
 
+## Announcement management
+
+An announcement is a _regular Hugo page_ contained under the `announcements`
+section of a locale. This means that we leverage Hugo's builtin handling of page
+dates (future or expired), internationalization, and more, to automatically show
+or hide banners depending on the build date, determine banner ordering, handle
+fall back to English banners, etc.
+
+> Announcements are currently used as banners only. We _might_ eventually
+> support slightly more general announcements as well.
+
+### Creating an announcement
+
+To add a new announcement, create an announcement markdown file under the
+`announcements` folder of your localization using the following command:
+
+```sh
+hugo new --kind announcement content/YOUR-LOCALE/announcements/announcement-file-name.md
+```
+
+Adjust according to your desired locale and file name. Add the announcement text
+as the body of the page.
+
+> For banners, the announcement body should be a short phrase.
+
+{{% alert title="For localizations" %}}
+
+If you are creating a **locale specific announcement override**, make sure that
+you use the **same filename** as the English language announcement.
+
+{{% /alert %}}
+
+### Announcement list
+
+Any given announcement will appear in a site build when the build date falls
+between the `date` and `expiryDate` fields of the announcement. When those
+fields are missing they are assumed to be "now" and "forever", respectively.
+
+Announcements will appear in the standard page order as determined using Hugo's
+[Regular pages](https://gohugo.io/methods/site/regularpages/) function. That is,
+the "lightest" announcements (by `weight`) will appear first; when weights are
+the same or unspecified, the most recent announcements (by `date`) will appear
+first, etc.
+
+So, if you want to force an announcement to the top, use a negative `weight` in
+the front matter.
+
 ## Contribute to other repositories
 
 OpenTelemetry is an open source project, and we gladly accept new contributions

content/ja/_index.md

@@ -4,6 +4,7 @@ description: >-
   効果的な観測を可能にする、高品質でユビキタスかつポータブルなテレメトリー
 developer_note:
   blocks/coverコラム（以下で使用）は、ファイル名に "background" を含む画像ファイルを背景画像として使用します。
+show_banner: true
 default_lang_commit: 902043db
 ---
 

content/ja/announcements/otel-community-day.md

@@ -0,0 +1,12 @@
+---
+title: OTel Community Day
+date: 2024-04-05
+expiryDate: 2024-06-25
+weight: -1 # top
+default_lang_commit: 788509efd404ba35dd113b4f37bae96ca7558e3e
+---
+
+<i class="fas fa-bullhorn"></i>
+6月25日に開催される
+[**OTel コミュニティデー**](https://events.linuxfoundation.org/open-telemetry-community-day/)
+にご参加ください

content/zh/_index.md

@@ -6,6 +6,7 @@ show_banner: true
 developer_note:
   下文所用的 blocks/cover 短代码将使用文件名中包含 "background"
   的图像文件作为背景图。
+show_banner: true
 default_lang_commit: 6e35a949
 ---
 

content/zh/announcements/otel-community-day.md

@@ -0,0 +1,12 @@
+---
+title: OTel Community Day
+date: 2024-04-05
+expiryDate: 2024-06-25
+weight: -1 # top
+default_lang_commit: 788509efd404ba35dd113b4f37bae96ca7558e3e
+---
+
+<i class="fas fa-bullhorn"></i>
+加入我们，参加
+[**OTel 社区日**](https://events.linuxfoundation.org/open-telemetry-community-day/)
+6月25日

hugo.yaml

@@ -212,16 +212,34 @@ module:
   mounts:
     - source: content/en
       target: content
+
+    ## ja
     - source: content/ja
       target: content
       lang: ja
+    # fallback pages
+    # - excludeFiles: specs/*
+    #   source: content/en/docs
+    #   target: content/docs
+    #   lang: ja
+    - source: content/en/announcements
+      target: content/announcements
+      lang: ja
+
+    ## zh
     - source: content/zh
       target: content
       lang: zh
+    # fallback pages
     - excludeFiles: specs/*
-      source: content/en/docs # zh missing-page fallback
+      source: content/en/docs
       target: content/docs
       lang: zh
+    - source: content/en/announcements
+      target: content/announcements
+      lang: zh
+
+    # Other site content
     - source: tmp/otel/specification
       target: content/docs/specs/otel
     - source: tmp/opamp

layouts/_default/baseof.html

@@ -10,7 +10,7 @@
       {{ partial "navbar.html" . }}
     </header>
     <div class="container-fluid td-default td-outer">
-      {{- partial "banner.md" . | .RenderString }}
+      {{- partial "banner.html" . }}
       <main role="main" class="td-main">
         {{ block "main" . }}{{ end }}
       </main>

layouts/partials/banner.html

@@ -0,0 +1,10 @@
+{{ if .Params.show_banner -}}
+  {{ $announcements := site.GetPage "announcements" -}}
+  {{ if $announcements -}}
+    <div class="o-banner">
+      {{ range $announcements.RegularPages }}
+      <div>{{ .Content }}</div>
+      {{ end -}}
+    </div>
+  {{ end -}}
+{{ end -}}

package.json

@@ -5,7 +5,7 @@
   ],
   "scripts": {
     "__check:links": "make --keep-going check-links",
-    "_build": "npm run _hugo -- -e dev -DFE --baseURL \"${DEPLOY_PRIME_URL:-http://localhost}\"",
+    "_build": "npm run _hugo -- -e dev --buildDrafts --baseURL \"${DEPLOY_PRIME_URL:-http://localhost}\"",
     "_check:format:any": "npx prettier --check --ignore-path ''",
     "_check:format": "npx prettier --check .",
     "_check:links--md": "npx markdown-link-check --config .markdown-link-check.json *.md",
@@ -28,7 +28,7 @@
     "_prepare:docsy": "cd themes/docsy && npm install",
     "_prettier:any": "npx prettier --ignore-path ''",
     "_rename-to-kebab-case": "find assets content static -name '*_*' ! -name '_*' -exec sh -c 'mv \"$1\" \"${1//_/-}\"' _ {} \\;",
-    "_serve:hugo": "hugo server -DFE --minify",
+    "_serve:hugo": "hugo server --buildDrafts --minify",
     "_serve:netlify": "netlify dev -c \"npm run _serve:hugo -- --renderToMemory\"",
     "_sync": "./scripts/sync-submodules.pl",
     "all": "bash -c 'x=0; for c in \"$@\"; do npm run $c || x=$((x+1)); done; ((!x)) || (echo \"ERROR: some scripts failed!\" && exit 1)' -",

scripts/i18n-check.sh

@@ -106,6 +106,9 @@ function main() {
     # if [[ -n $FLAG_VERBOSE ]]; then echo -e "All targets: $TARGETS"; fi
   fi
 
+  # set -x
+  # git branch -vv
+
   SYNCED=1
   for f in $TARGETS; do
     # if [[ -n $FLAG_VERBOSE ]]; then echo -e "Checking\t$f"; fi
@@ -120,6 +123,14 @@ function main() {
     if [[ -z $LASTCOMMIT ]]; then
       # Get last commit of `main` that this branch is rooted from.
       LASTCOMMIT=$(git merge-base main HEAD)
+    # elif ! git branch --contains $LASTCOMMIT | grep -q "^\s*main\b"; then # HERE
+    #   # Get last commit of `main` that this branch is rooted from.
+    #   LASTCOMMIT=$(git merge-base main HEAD)
+    # fi
+
+    # if ! (git branch --contains $LASTCOMMIT | grep -q "^\s*main\b"); then
+    #   echo "Something is wrong, the hash is empty or isn't on 'main', aborting: $LASTCOMMIT - $f"
+    #   exit 2
     fi
 
     if [[ -n $FLAG_UPDATE ]]; then
@@ -145,7 +156,7 @@ function main() {
     fi
   done
   if [ $SYNCED -ne 1 ]; then
-    exit 1
+    exit
   fi
 
   echo "$TARGET_PATHS is still in sync"

static/refcache.json

@@ -4811,6 +4811,10 @@
     "StatusCode": 206,
     "LastSeen": "2024-06-06T14:51:47.628909-04:00"
   },
+  "https://gohugo.io/methods/site/regularpages/": {
+    "StatusCode": 206,
+    "LastSeen": "2024-06-07T12:38:33.735717-04:00"
+  },
   "https://golang.org/ref/spec#Slice_types": {
     "StatusCode": 200,
     "LastSeen": "2024-01-18T19:02:17.04578-05:00"