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/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. 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 公開を集約する