update-site-for-release

<!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> Local override: `$TIKA_SKILLS_LOCAL/update-site-for-release/LOCAL.md` (default `~/.tika-skills`), read after this file, wins on conflict. # Update the Tika website for a release Step 17 ("Update Tika site") of the Release Process (<https://cwiki.apache.org/confluence/spaces/TIKA/pages/109454070/Release+Process>). Assumes the release (tag, artifacts, VOTE, dist promotion) is done; covers the **website** only. **First: `cd $SITE && svn update`.** The checkout is usually behind (docs republishes, logo/security edits land between releases); a stale base only surfaces at the very end, after the 67 MB commit has uploaded, as `E155011 ... is out of date`, and the whole transaction rolls back. Set these first: - **`$SITE`** — `tika-site` **SVN** checkout (not git): `src/site/` (sources) + `publish/` (generated, SVN-tracked, served; `mvn install` regenerates it and auto-runs `svn add --force publish` via antrun). - **`$SCRATCH`** — release working dir: unzipped src release, `CHANGES-<NEW>.txt`, built javadoc. Scripts: `./scripts/`. Local paths + toolchain (Maven binary, JDKs) live in a private companion skill under `~/.claude/skills/`. > **[HUMAN] gates — never do these yourself:** final `svn commit` (outward-facing, > irreversible), JIRA "release", s.apache.org shortlink, announce emails. Prepare > everything, show `svn status`, hand off. --- ## 0. Inputs + release track Two supported tracks since 4.0.0 (2026-08-21): **4.x** is the current line, **3.x** is the maintenance line. Which track a release is on decides the process; both tracks are "stable" — there is no preview slot unless a future 5.x preview reintroduces one. | Input | Example | Notes | |---|---|---| | `NEW_VERSION` | `4.0.1` | the release | | `RELEASE_TRACK` | `4.x` | `4.x` or `3.x` (maintenance) | | `PREV_TAG` / `NEW_TAG` | `4.0.0-rc1` / `4.0.1` | git tags, for the GitHub contributor query | | `JIRA fixVersion` | `4.0.1` | **may differ** from the label (pre-releases often use the base version) | | `CHANGES` file | `$SCRATCH/CHANGES-4.0.1.txt` | notable-changes source | | src release zip | `tika-<NEW>-src.zip` | javadoc source (both tracks) | | release date | `2026-08-21` | doap.rdf + news blurb | Confirm current values in `pom.xml` (repo root — `tika.stable.version` = 4.x line, `tika.maintenance.version` = 3.x line). **Before starting, check the final git tag exists** (`git ls-remote --tags https://github.com/apache/tika | grep <NEW>`). The vote passes on an `-rcN` tag and nothing creates the plain `<NEW>` tag; 4.1.0 shipped with only `4.1.0-rc3`. Ask the RM to tag the rc commit (`git tag <NEW> <NEW>-rcN^{}` + push) — the contributor query, the docs branch and the next release's `PREV_TAG` all want it. Until then use the rc tag for `--tag`. | Step | 4.x track | 3.x maintenance track | |---|---|---| | `pom.xml` `<parent><version>` | leave at newest 3.x | → `<NEW>` (must stay a 3.x parent — Java 11 build) | | `pom.xml` `tika.stable.version` | → `<NEW>` | leave | | `pom.xml` `tika.maintenance.version` | leave | → `<NEW>` | | `src/site/apt/<NEW>/` | **only `index.apt`** (Changes) | full 8-file set (scaffold from prev 3.x) | | `site.xml` entry | sub-menu linking `docs/<X.Y>.x/` pages + Changes + api | full legacy sub-menu, expanded | | formats.apt | n/a — `docs/.../formats.adoc`; its generated partial is test-enforced | regenerate from `tika-app` jar | | javadoc | `clean install -Pfast` + `javadoc:aggregate` → `publish/<NEW>/api` (step 7) | same | | Antora docs | new minor → new `docs/<X.Y>.x` branch; patch → republish same branch (step 7) | n/a | | Download page | automatic | automatic | doap.rdf, index.apt.vm news, verify, publish are common to both. URL scheme (decided 2026-08-19): Antora docs are per-minor (`/docs/4.0.x/`); the apt Changes page and javadoc are per-release (`/4.0.0/`, `/4.0.0/api/`) — javadocs are exact-version artifacts. --- ## 1. `pom.xml` versions (repo root) [AGENT] - **4.x:** bump `<tika.stable.version>` to `<NEW>`. - **3.x:** bump `<tika.maintenance.version>` **and** `<parent><version>` to `<NEW>`. - `<parent>` supplies build config only (no site content references it since 4.0.0). It must stay on the newest **3.x** parent: the 4.x parent enforces Java 17, but maven-site-plugin 3.4 needs the Java 11 build (step 8). Download page auto-reads these — no manual edit. (`download.apt.vm` also derives `$docsLine` = `4.1.x` from `tika.stable.version` for its Antora links; check the artifact list against `dist/release/tika/<NEW>/` if the distribution set changed.) --- ## 2. `src/site/site.xml` menu [AGENT] Current 4.x + current 3.x expanded; older = `collapse="true"`. - **4.x, new minor:** new expanded block at the top; links go into the Antora tree plus the per-release Changes/api (repoint `docs/<old>.x` → `docs/<new>.x` when a new minor supersedes; a patch release only updates the Changes/api version numbers in the hrefs): ```xml <item name="Apache Tika 4.0.0" href="docs/4.0.x/index.html"> <item name="Documentation Home" href="docs/4.0.x/index.html"/> <item name="Supported Formats" href="docs/4.0.x/formats.html"/> <item name="Using Tika" href="docs/4.0.x/using-tika/index.html"/> <item name="Getting Started (Java API)" href="docs/4.0.x/using-tika/java-api/getting-started.html"/> <item name="Pipes" href="docs/4.0.x/pipes/index.html"/> <item name="Configuration" href="docs/4.0.x/configuration/index.html"/> <item name="Migrating to Tika 4.x" href="docs/4.0.x/migration-to-4x/index.html"/> <item name="Changes" href="4.0.0/index.html"/> <item name="API Documentation" href="4.0.0/api/"/> </item> ``` - **3.x:** new expanded block above the previous 3.x; add `collapse="true"` to the old block: ```xml <item name="Apache Tika 3.3.2" href="3.3.2/index.html"> <item name="Getting Started" href="3.3.2/gettingstarted.html"/> <item name="Supported Formats" href="3.3.2/formats.html"/> <item name="Parser API" href="3.3.2/parser.html"/> <item name="Parser 5min Quick Start Guide" href="3.3.2/parser_guide.html"/> <item name="Content and Language Detection" href="3.3.2/detection.html"/> <item name="Configuring Tika" href="3.3.2/configuring.html"/> <item name="Usage Examples" href="3.3.2/examples.html"/> <item name="API Documentation" href="3.3.2/api/"/> </item> ``` --- ## 3. Per-version apt docs `src/site/apt/<NEW>/` [AGENT] **4.x** — create only `index.apt` (the Changes page; title `Apache Tika <NEW>`; fill step 4). No other apt files — everything else lives in the Antora docs. **3.x** — scaffold (these docs are version-string-identical across 3.x): ```bash ./scripts/scaffold-stable-version.sh $SITE 3.3.1 3.3.2 ``` Copies+bumps `configuring/detection/examples/parser/parser_guide/gettingstarted.apt`. Then: - **formats.apt** — two parts: a hand-written top (license, intro, `%{toc}`, ~25 prose format-family sections) down to the header line `Full list of Supported Formats in "standard" artifacts`, then a generated flat list below it. `--list-parser-details-apt` regenerates only the flat part. Copy prev `formats.apt`, bump versions, replace everything **below** that header: ```bash java -jar <path>/tika-app-<NEW>.jar --list-parser-details-apt ``` **Do NOT truncate at the `%{toc}` line** — keep the prose sections. (Scaffold skips `formats.apt` for this reason.) - **index.apt** — step 4. --- ## 4. Per-version `index.apt`: notable changes + contributors [AGENT + HUMAN] Shape (see `src/site/apt/3.3.1/index.apt`): license+title; "most notable changes…" bullets; "The following people have contributed…" bullets; "See {{https://s.apache.org/XXXX}} …". **Notable changes** — review output, keep only notable items: ```bash ./scripts/extract-tika-issues.py CHANGES-3.3.2.txt out-3.3.2.apt 3.3.2 ``` Mirrors CHANGES verbatim; TIKA-####/Github-#### auto-linked; ALL-CAPS headers (incl. `SERVER, PIPES AND OPERATIONS`, `INFERENCE (EXPERIMENTAL)`) → apt sections; apt markup chars in prose (`<= 0`, `type->parser`, `{x}`, `[]`, `~35%`) are backslash-escaped — an unescaped `<` fails the site build with `Error parsing '.../index.apt': line [N] missing '>'`; output is wrapped at 78 cols without splitting hyphenated words or links. **Contributors** — candidate list, RM curates: ```bash ./scripts/extract-tika-contribs.py 3.3.2 --prev-tag 3.3.1 --tag 3.3.2 > contribs.txt # beta (fixVersion differs from label): # ./scripts/extract-tika-contribs.py 4.0.0 --prev-tag 3.3.1 --tag 4.0.0-beta-1 ``` Merges JIRA (reporters/assignees/comment authors) + GitHub commit/PR authors (uses `gh` auth; resolves logins→names; case-insensitive sort; filters bots/AI). Over-reports drive-by commenters, misses GitHub-issue-only commenters. **[HUMAN]** prune / normalise / add. **Shortlink [HUMAN]** — `s.apache.org/XXXX` → the JIRA "issues fixed in <NEW>" query; needs s.apache.org login. Ask the RM. --- ## 5. `src/site/resources/doap.rdf` [AGENT] New `<release>` at the top. Ordering is by **date, not version** (a stable point release can sit above an older-dated preview — 3.3.2/Jul-16 above 4.0.0-beta-1/Jul-3): ```xml <release> <Version> <name>Apache Tika 3.3.2</name> <created>2026-07-21</created> <revision>3.3.2</revision> </Version> </release> ``` --- ## 6. Home page `src/site/apt/index.apt.vm` [AGENT + HUMAN] 1. New **Latest News** block at the top; its CHANGES link uses `dist.apache.org/repos/dist/release/...` (live mirror): ``` [21 July 2026: Apache Tika Release] Apache Tika 3.3.2 has been released! <one or two sentence summary>. Please see the {{{https://dist.apache.org/repos/dist/release/tika/3.3.2/CHANGES-3.3.2.txt}CHANGES.txt}} file for the full list of changes in the release and have a look at the download page for more information on how to obtain Apache Tika 3.3.2. ``` 2. **Repoint the superseded release's CHANGES link** (its artifacts get `svn rm`'d from the live mirror at release): `dist.apache.org/repos/dist/release/tika/<PREV>/…` → `archive.apache.org/dist/tika/<PREV>/…`. **[HUMAN]** confirm which version was removed. ---