CI/CDに関係するドキュメントを更新・整理する

[ghost]

PR の目的

CI/CD関連のドキュメントを更新し、適切と思われるディレクトリへ移動する

カテゴリ

• ドキュメント修正

PR の背景

これまで行われたビルド構成の改善により、ドキュメントの内容が現状にそぐわなくなっているので更新する

• Azure Pipelines のドキュメントに記載されている構成が現状と異なる。
• AppVeyor のドキュメントに記載されているビルド用バッチファイルの構成が現状と異なる。
  • このドキュメントの内容はローカルを含むAppVeyor以外でのビルドにも適用される内容です。
• CIで利用しているにも関わらず、ドキュメントに記載されていない環境変数がある。
  • このドキュメントの内容はCIに関連する環境変数のリストなので、タイトルが不正確な気がしました。

確認できる範囲で、内容を変更する理由となるPRを関連項目に記載しました。

PR のメリット

PR のデメリット (トレードオフとかあれば)

仕様・動作説明

今回行ったタイトルの改題と移動は次の通りです。

• ./appveyor.md → ./ci/build-batchfiles.md
  • タイトルを「ビルドに使用されるバッチファイル」へ改題
  • CIビルドのスキップ方法に関する記述を./build.mdへ移動
• ./azure-pipelines.md → ./ci/azure-pipelines/azure-pipelines.md
  • タイトルに変更はありません。
• ./ci-build.md → ./ci/build-envvars.md
  • タイトルを「CI でのビルドにて使用される環境変数」へ改題

なお、CIからの入力として利用している環境変数についてですが、実際にはappveyor_env.pyが次の3つを利用しています。

• APPVEYOR_BUILD_FOLDER
• APPVEYOR_REPO_COMMIT
• APPVEYOR_REPO_TAG_NAME

文書はgithash.batを対象としたものであることから追記していません。
（ただ、appveyor_env.pyをAzure Pipelinesでも活用できるように作り直すべきだと思いました。）

PR の影響範囲

テスト内容

テスト1

手順

関連 issue, PR

ファイル整理

• トップディレクトリのファイルを整理する #740 リポジトリのルートディレクトリを整理したい

バッチファイルの処理内容

• パッケージ関連のログ出力を抑制する #480 成果物の内容をログ出力しないようにした（listzip.batを呼ばなくした）
• azure pipelines で代用可能な処理を appveyor で実施しないようにする #833 build-all.batでcppcheckとdoxygenを実行しないようにした
• HTMLヘルプの文字コードを変換する簡易ツールを導入する #996 HTMLヘルプの文字コード変換ツールを導入
• 自動生成ファイルの生成タスクを整理する #1029 preBuild.batの処理内容の一部をtarget化
• tag に対するビルドで成果物名にタグ名が含まれないのを修正 #1127 成果物名にGitのタグ名も含めるようにした
• MSVCビルドでMinGWビルド向けのMakefileが更新されるとMakefileが壊れるのでMakefile更新をやめたい #1387 MakefileMake.exeの廃止
  • これ以降、preBuild.batにて実行される処理はありません。
• HTMLヘルプのビルドステップをpowershellに移植してエラー耐性を上げる #1509 AppVeyorの疑似パイプラインを廃止
  • これ以降、make-artifacts.batは使われていないようです。

CI/CD

• SonarQube (SonarCloud) 対応 #674 SonarQubeを導入
• azure pipelines でインストーラのビルドを行う #826 Azpにてインストーラのビルド・cppcheck・doxygenを行う
• Azure Pipelines ですべての python スクリプトのコンパイル確認を行う #848 Pythonスクリプトのコンパイル確認ジョブをAzpに追加
• MinGWビルドを引っ越しする #983 MinGWビルドのジョブをAppVeyorからAzpに移動
• Azure Pipelines で VS2019 のビルドを行う #1147 AzpのVS2019対応
• Appveyor 専用の環境変数を汎用的なものに定義しなおして azure pipelines で使えるようにする #1183 AppVeyor専用の環境変数を汎化してAzpでも使う（追加したものの表に記載されなかった環境変数がありました。）

参考資料

[ghost]

ひとまず作業が終わりましたのでDraftを外しておきます。

本文に記載したことのほかに気が付いたことをメモしておきます。

• calc-hash-res.batとmake-artifacts.batは利用されていないようです。
• get-PR.mdと内容が完全に同一なWiki項目があるため、そちらに1本化したいです。
• zipArtifacts.batはsetlocalコマンドが記述されているため、ドキュメントに記載した環境変数をほかのバッチファイルから参照できないように見えます。このため、ドキュメントに記載する必要性を感じませんでした。
  • なお、setlocalがないことで、あるバッチファイルが定義した環境変数がほかのバッチファイルによって上書きされるパターンもあるようでした。

[ghost]

[WIP] が付いたままだった。

[berryzplus]

変更目的と訂正範囲は妥当に見えています。

こういう修正はアラ探しすればいくらでも不審点が見つかると思うので
ドキュメント詳細の妥当性は検証せずにapproveしてしまいます。

変更内容の詳細が厳密に「正しい」かどうかについてはみてないので、
この内容で困る人がいたら。適宜追加の変更を提案してもらえば良いと思っています。

[ghost]

approveありがとうございました。
マージしてしまいます。

追加の修正等、要望がありましたら別途対応いたしますのでお知らせください。