From 1cec65ef360dbc2b17970ee6699c12840fc9a3ae Mon Sep 17 00:00:00 2001 From: wrongwrong Date: Sat, 8 Aug 2026 14:47:01 +0900 Subject: [PATCH 1/2] =?UTF-8?q?ci:=20API=20=E3=83=89=E3=82=AD=E3=83=A5?= =?UTF-8?q?=E3=83=A1=E3=83=B3=E3=83=88=E3=82=92=20Pages=20=E3=81=B8?= =?UTF-8?q?=E6=8E=B2=E8=BC=89=E3=81=99=E3=82=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit リリース毎に Dokka HTML を GitHub Pages へ deploy する。deploy はサイト全体を置き換えるため、 過去版の閲覧を保つには生成のたびに全版を作り直す必要がある。版切替 UI を出す Dokka の versioning プラグインを入れ、過去版の出力は gh-pages ブランチを保管場所として持つ。 保管するのは各版の出力から older/ を除いたもので、除かないと版を重ねるたびに過去版が 入れ子で積み上がる。保管ブランチの更新は通常のコミットで行う（保護設定と整合させるため）。 Co-Authored-By: Claude Opus 5 --- .github/workflows/publish.yml | 73 +++++++++++++++++++++++++++++++++++ build.gradle.kts | 18 ++++++++- 2 files changed, 90 insertions(+), 1 deletion(-) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 1b601be..24b5ee0 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -78,3 +78,76 @@ jobs: env: GH_TOKEN: ${{ github.token }} run: gh release create "$GITHUB_REF_NAME" --verify-tag --title "$GITHUB_REF_NAME" --generate-notes + + # API ドキュメントの掲載。Pages のソースは Actions のため、公開されるのはこのジョブが上げる成果物であり、 + # 保管ブランチ（gh-pages）の内容が直接配信されることはない。同ブランチは過去版の出力だけを + # versions/<版>/ の形で持ち、版切替 UI の入力として使う。deploy はサイト全体を置き換えるため、 + # 過去版の保持はこの保管場所から毎回作り直すことで成り立つ + docs: + needs: publish + runs-on: ubuntu-latest + timeout-minutes: 60 + permissions: + contents: write + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deploy.outputs.page_url }} + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/setup-java@b6effb05e454b25005698d916606bdc6ffcbf961 # v5.7.0 + with: + distribution: temurin + java-version: 17 + - uses: gradle/actions/setup-gradle@9c971963bec38e04b3d30dcc455b5382be2fdbfb # v6.3.0 + + # 初回リリース時は保管ブランチがまだ無い。その場合は空の履歴から始める + - name: Restore archived versions + env: + GH_TOKEN: ${{ github.token }} + run: | + set -euo pipefail + url="https://x-access-token:${GH_TOKEN}@github.com/${{ github.repository }}.git" + if git ls-remote --exit-code --heads "$url" gh-pages >/dev/null 2>&1; then + git clone --branch gh-pages --depth 1 "$url" build/gh-pages + else + mkdir -p build/gh-pages + git -C build/gh-pages init -b gh-pages -q + git -C build/gh-pages remote add origin "$url" + fi + mkdir -p build/gh-pages/versions + + - run: ./gradlew dokkaGenerate -PolderDocsDir=build/gh-pages/versions + + # 保管するのは各版の出力そのものとし、生成物に含まれる過去版（older/）は落とす。 + # 落とさないと版を重ねるたびに過去版が入れ子で積み上がる + - name: Archive this version + run: | + set -euo pipefail + dest="build/gh-pages/versions/${GITHUB_REF_NAME#v}" + rm -rf "$dest" + mkdir -p "$dest" + cp -r build/dokka/html/. "$dest/" + rm -rf "$dest/older" + + # 保管ブランチの更新は通常のコミットで行う（force push は保護設定と整合しない） + - name: Update archive branch + working-directory: build/gh-pages + run: | + set -euo pipefail + git config user.name "github-actions[bot]" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + git add -A + if git diff --staged --quiet; then + echo "::notice::archive is already up to date" + else + git commit -q -m "docs: ${GITHUB_REF_NAME#v} の API ドキュメントを保管する" + git push origin gh-pages + fi + + - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0 + with: + path: build/dokka/html + - id: deploy + uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0 diff --git a/build.gradle.kts b/build.gradle.kts index d59a592..7a6a61a 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -157,7 +157,8 @@ val versionMentionRules: List> = // 対象箇所: README（セットアップ例・互換表・検証済みビルド環境）・概要 §7（版形式の現行例）・ // 実装ノート / テスト戦略 / エッジケースへの対応方針（実測・テスト環境の宣言）・kotlinc.xml。 -// 現行版への言及を持つ資料を増やした場合はここへ追加する +// 現行版への言及を持つ資料を増やした場合はここへ追加する。 +// ただし過去の版を記録する文書（CHANGELOG）は対象にしない。履歴の版が現行版へ書き換えられてしまう val versionMentionTargets = listOf( "README.md", @@ -247,6 +248,21 @@ tasks.named("ktfmtFormat") { dependsOn(ktfmtFormatIntegrationTest) } dependencies { dokka(project(":sealed-class-enumizer-runtime-api")) dokka(project(":sealed-class-enumizer-gradle-plugin")) + // 版切替 UI を出すための Dokka プラグイン（HTML 形式のみが対象）。版指定は要らず、適用中の Dokka へ揃う + dokkaHtmlPlugin("org.jetbrains.dokka:versioning-plugin") +} + +// 過去版の出力は保管場所から展開したディレクトリを -PolderDocsDir で渡す（版毎のサブディレクトリを持つ親を指す）。 +// 指定が無い場合は現行版だけの出力になるため、ローカルでの生成は保管場所を用意せずに行える +dokka { + pluginsConfiguration { + versioning { + version = enumizerFullVersion + providers.gradleProperty("olderDocsDir").orNull?.let { + olderVersionsDir = layout.projectDirectory.dir(it) + } + } + } } // integration-test の TestKit フィクスチャ向けに、3 モジュールのローカル Maven 公開を集約する From 2a351d3e1d79d214ee0dd9778529cbc36e648910 Mon Sep 17 00:00:00 2001 From: wrongwrong Date: Sat, 8 Aug 2026 14:47:01 +0900 Subject: [PATCH 2/2] =?UTF-8?q?docs:=20CHANGELOG=20=E3=82=92=E8=BF=BD?= =?UTF-8?q?=E5=8A=A0=E3=81=99=E3=82=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit リリース毎の変更点の記載先を用意する。初回は機能の説明を README が担うため記載を置かない。 版表記の同期タスクの対象には含めない（履歴として残す過去の版が、現行版へ書き換えられてしまうため）。 Co-Authored-By: Claude Opus 5 --- CHANGELOG.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..8dca9f8 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,14 @@ +# Changelog + +Notable changes to this project are documented here. +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). + +Artifacts are versioned as `-`, and all artifacts are released together +under the same version. See [Versioning and support policy](README.md#versioning-and-support-policy) +for what each part means. + +## [Unreleased] + +## [2.4.10-0.1.0] + +Initial release.