JuliaRegistrator や TagBot でtag 打ちをしても stable Document が生成されない対処法
本日は
General に登録した(≒いわゆる公式パッケージと呼ばれているもの)パッケージを日々メンテしていくとドキュメントもメンテしたくなります.stable 版のリンクが生成されない問題を解決しましたので情報共有したいと思います.
現象
リリースタグをつけてるのに対応するバージョンのリンクが作成されない.
dev
しか出ないが・・・???
期待する結果
Julia の Documentation のように各バージョンごとのドキュメントのリンクが作成されて欲しい
分かったこと
DOCUMENTER_KEY
の設定を行う必要があった.
文脈の補足
なぜこういう話が出てくるようになったかの文脈を補足します.公式パッケージをリリースしたあとメンテする際にハマる気がしたので書いておこうと思ったからです.
公式パッケージとして登録した後のメンテ方法
昔書いた Qiita 記事も参考にしてください:
バージョンの更新
例えば,読者は,PkgTemplates.jl を利用しパッケージの雛形を作ったとします.そして何かしらの機能を提供する Julia パッケージを GitHub などで公開したとします. それを Julia の,「いわゆる公式パッケージ」にしたとします.ここで「いわゆる公式パッケージ」というのは Julia のパッケージ情報を格納する General レジストリ に登録されたものを指しています.
初期のバージョン 0.1.0
から機能追加,バグ修正を main ブランチにマージしそろそろ安定板をリリースしたいと仮定します. 例えばバージョン番号を 0.2.0
としてリリースしたいとします.
どういうふうにバージョン番号を上げていくかは https://semver.org/#summary を見ると良いです.
まずはメンテナンスしているパッケージの Project.toml
を編集し 0.1.0
を 0.2.0
に変更しましょう.
Before:
name = "YourPkg"
uuid = "xxxxxxx"
authors = ["Goma-chan kawaii and contributors"]
version = "0.1.0"
After:
name = "YourPkg"
uuid = "xxxxxxx"
authors = ["Goma-chan kawaii and contributors"]
version = "0.2.0"
この変更を行う, ブランチを作り, コミット, そしてプルリクエストをだして GitHubAction の CI が通ったことを確認しマージします.
作業を JuliaRegistrator bot に依頼
GitHub のリポジトリ直下でマージした後のコミットのハッシュをクリックします(下図参照,この場合 fc16524
をクリック).
コメント欄で下記のメッセージをコメントとして書きます.
@JuliaRegistrator register
このリンク を参考にしてください:
あとは全て JuliaRegistrator
bot General に自動プルリクエストを作成します.
General 側でのCIが通り特に問題がなければ自動的にマージされます.
そのあとは?
インターネット上にある PkgTemplates.jl でパッケージの雛形を作る方法に従うと .github/workflows/TagBot.yml
が生成されているはずです:
name: TagBot
on:
issue_comment:
types:
- created
workflow_dispatch:
jobs:
TagBot:
if: github.event_name == 'workflow_dispatch' || github.actor == 'JuliaTagBot'
runs-on: ubuntu-latest
steps:
- uses: JuliaRegistries/TagBot@v1
with:
token: ${{ secrets.GITHUB_TOKEN }}
ssh: ${{ secrets.DOCUMENTER_KEY }}
General レジストリで自動PRがマージされるとこの結果をトリガーにし TagBot.yml
で定義された Action が動作します. これでリリースタグ v0.2.0
が Release ページに生成されます.
ここからが本番
さて,本来ならリリースタグを作成することで v0.2.0 用のソフトウェアドキュメントが Documenter.jl によって作られるはずです.でも出ないんです.
TagBot のドキュメントを読む
https://github.com/JuliaRegistries/TagBot の README を読みましょう.
You may, however, want to customize the behaviour via the available configuration options.
For example, if you use GitHub Actions to build the documentation for your package, you will find that with the default TagBot configuration, your documentation build is not triggered when a new tag is created. In this case, you will need to use SSH Deploy Keys.
Read on for a full description of all of the available configuration options.
はーん...
your documentation build is not triggered when a new tag is created.
なるほど.つまり色々設定が必要だったようです.リリースタグをリポジトリの管理者が手動で作成する場合は特に困ることはないですけれど,botを経由して自動でリリースタグを作った場合は SSH Deploy Keys
を作る必要があるようです.
作り方
作業の方針は Qiita に書いていたもの をベースにすればOKです.Qiita の記事は古くなったので Zenn の上で更新します.
DocumenterTools.jl の導入
下記のように DocumenterTools.jl を導入します.
julia> using Pkg
julia> Pkg.add("DocumenterTools")
REPL で下記を実行します:
julia> using DocumenterTools
julia> DocumenterTools.genkeys(user="YourGitHubUserName", repo="YourPkg.jl")
ここで GitHub で管理しているリポジトリのURLが https://github.com/YourGitHubUserName/YourPkg.jl
の場合を仮定しています.
YourGitHubUserName
は会社だったり組織だったりするかもしれません. 適宜読み替えてください. 出力は下記のようになります:
[ Info: add the public key below to https://github.com/YourGitHubUserName/YourPkg.jl/settings/keys with read/write access:
ssh-rsa <みじかーい文字列>= Documenter
[ Info: add a secure environment variable named 'DOCUMENTER_KEY' to https://travis-ci.com/YourGitHubUserName/YourPkg.jl/settings (if you deploy using Travis CI) or https://github.com/YourGitHubUserName/YourPkg.jl/settings/secrets (if you deploy using GitHub Actions) with value:
<ながーーーい文字列>
上記のログを冷静に眺めれば
https://github.com/YourGitHubUserName/YourPkg.jl/settings/keys
にアクセスし ssh-rsa <みじかーい文字列>= Documenter
の値を登録すればOKです.その際にread/write access
にチェックを入れる必要があります.
さらに
https://github.com/YourGitHubUserName/YourPkg.jl/settings/secrets
にアクセスし DOCUMENTER_KEY
という名前で保存します.この DOCUMENTER_KEY
は TagBot.yml
にあるものと対応していると理解すればOKです.
'JuliaTagBot'
runs-on: ubuntu-latest
steps:
- uses: JuliaRegistries/TagBot@v1
with:
token: ${{ secrets.GITHUB_TOKEN }}
ssh: ${{ secrets.DOCUMENTER_KEY }} # <---- こいつのこと
あとは次回のリリース作業をすれば TagBot さんが ssh キーを検知しよしなに stable 用のページを作ってくれます.
Author And Source
この問題について(JuliaRegistrator や TagBot でtag 打ちをしても stable Document が生成されない対処法), 我々は、より多くの情報をここで見つけました https://zenn.dev/terasakisatoshi/articles/87e730a50915f9著者帰属:元の著者の情報は、元のURLに含まれています。著作権は原作者に属する。
Collection and Share based on the CC protocol