[iutest] ドキュメントの置き場を GitHub Pages に集約した

issue いただきまして iutest のドキュメントの構成を変更しました。

（issue ありがとうございますmm）

これが、

こうなりました。

ドキュメントを GitHub Pages へ

まず OSDN においていた最新バージョンのドキュメントを GitHub Pages に引っ越ししました。

こちらのドキュメントは実は2年くらい更新をし忘れていました。。。

そこでドキュメントの更新は GitHub Actions でタグが作られたら自動で更新されるようにしました。

次にもともと GitHub Pages においていた master ブランチ HEAD バージョンのドキュメントですが、こちらはトップディレクトリから master ディレクトリに移動しました。ディレクトリ構成は以下のとおりです。

最新バージョンのドキュメントは latest ディレクトリに push されます。

OSDN からリダイレクト

続いてもともと OSDN にアップロードしていたドキュメントページにアクセスしたら、GitHub Pages にリダイレクトするように設定します。

まずはサーバーへのアクセスをします。（これまでもやってるはずですが、いつも忘れてしまうのでメモ）

OSDN のドキュメントはシェルサーバーの「/home/groups/<プロジェクトUNIX名の1文字目>/<プロジェクトUNIX名の1、2文字目>/<プロジェクトUNIX名>/」にあります。iutest の場合は「/home/groups/i/iu/iutest」です。サーバーには鍵を登録してアクセスします。

OSDN では .htaccess でリダイレクトの設定ができるので、OSDN ドキュメントのサンプルを参考に設定しました。

RewriteEngine on
RewriteBase /doc
RewriteRule ^(.*) https://srz-zumix.github.io/iutest/latest/$1 [R=301,L]

最後に

手動更新は早急にやめたほうがいいですね。

では。

osdn-cli でパッケージリリース

前置き

本当は CI サービスを使った自動パッケージリリースをやろうと思っていたのですが、最初に試した osdn-cli がローカルマシンで使う想定だったため、実現できませんでした。
CI サービスなどからリリースする場合は、ファイルリリース機能を使うのではなく、ファイルストレージ機能を使うといいみたいです。

あるプロジェクトからの要請でローカルなホーム上でのコマンドラインで使うことのみを想定したツールですので、ほぼ使えないかと思います。CIと連携する場合はファイルリリース機能ではなく、ファイルストレージ機能を使うほうが良いかと思います。

— Shuji Sado (@shujisado) 2018年6月29日

できあがったもの

なにはともあれ、osdn-cli を使ってパッケージリリースする方法は習得できたので、もったいないのでまとめました。

パッケージの作成

パッケージはすでに作成済みの前提です。
基本的にパッケージは一度作成したら変えることがないと思いますので、自動化から除外してます。

一応、
作成する場合は、 osdn package create で作成することができます。
既存かどうか判断しないと増え続けるので注意が必要です。
この辺はリリースの作成と同じような手順で対応できると思います。

リリースの作成

パッケージにリリースを作成します。以下のコマンドで作成しますが、まだファイルは一切アップロードしてない状態です。また、公開タイミングは手動で行うので、-v hidden オプションで非公開にしています。

osdn release create -v hidden --package $PACKAGE_ID $RELEASE_NAME

パッケージIDの取得

リリースを作成するときにパッケージの指定が必要になりますが、こちらは id 指定なので名前を指定してもダメです。
ID をベタ書きしてもいいのですが、汎用的に以下のコマンドで取得しました。

PACKAGE_ID=`osdn package | grep -o '[0-9]* iutest ' | cut -d ' ' -f 1`

パッケージのリストを出力、#ID 名前で出力されるので grep して ID を抽出してます。

リリースIDの取得

osdn release create では同名のリリースが既存であろうとなかろうと関係なくリリースを作成します。
そのため、すでに同名のリリースがあった場合は作成をスキップし、リリースIDの取得のみを行います。
リリースIDの取得は省略します。だいたいパッケージIDの取得と同じです。

最初に同名リリースを検索し、なければ osdn release create を行います。
その後リリースIDを取得しますが、これはファイルアップロードする際に利用するためです。

ファイルアップロード

osdn frs_upload --package $PACKAGE_ID --release $RELEASE_ID $FRS_RELEASE_ROOT

ファイルのアップロードは frs_upload を使いました。
パッケージとリリースIDを指定し、アップロードしたいディレクトリルートを渡したら OK です。
iutest のスクリプトでは、frs_mkdirs で各リリースのディレクトリを構築して、そこにリリースするファイルをコピーして、それをアップロードする形にしました。

アップロード後の作業

リリースノート・変更履歴の設定

上記リリーススクリプトで、リリースノートと変更履歴のファイルもアップロードするようにしています。
RELEASENOTE や CHANGELOG といった予め決められたファイル名のファイルを認識してくれる機能を利用しています。
ファイルリリースガイド - OSDN ヘルプ - OSDNドキュメント管理 - OSDN

ただ、このファイルをアップロードしてもそれだけではリリースノート・変更履歴として、表示されませんでした。これらのファイルを表示させるには、リリースの編集からチェックを変更して保存する必要がありました。


これ、ちょっと面倒ですね。。。


あ、あと、リリースノートとか変更履歴のファイルは非公開にすると、当然のようにリリースに表示されなくなります。
（別にファイルとしてダウンロードさせたいわけじゃないので、ファイルは非公開だけどリリースには表示されると嬉しかった）

ステータスを公開に変更する

リリース作成・ファイルアップロードを自動化しましたが、公開状態にするのは手動でやるように あえて したので、公開準備ができたらリリースページに移動して、ステータスを公開にします。



これで、リリース作業が完了しました。

最後に

デプロイを自動化、 CI サービスで動かして完全自動化といきたいとこでしたが、
それでも今まで手動で AppVeyor からパッケージダウンロードして、手動で OSDN のリリースを作成していたのを考えれば大分楽になりました。
引き続き、このスクリプトは利用しますが、ファイルストレージ機能を使ったデプロイになる早で移行したいなーと思います。

ではでは。