GitHub - Releasesのソースを表示

== 概要 ==
GitHub Releasesは、ソフトウェアの特定バージョンをパッケージ化して配布するための機能である。<br>
<br>
ReleaseはGitのタグをベースに構築され、リリースノート、バイナリファイル、ドキュメントなどをまとめて公開できる。<br>
<br>
下表に、Releasesが提供する主な機能を示す。<br>
<br>
<center>
{| class="wikitable"
|+ GitHub Releasesの主な機能
|-
! 機能 !! 説明
|-
| バイナリ配布 || コンパイル済みの実行ファイルやライブラリをアセットとして添付して、ユーザに直接提供できる。
|-
| リリースノート || 変更内容、バグ修正、新機能をまとめたノートを自動生成または手動で記述できる。
|-
| バージョン管理 || セマンティックバージョニングに従ったタグと紐付けることにより、バージョン履歴を明確に管理できる。
|-
| ドラフト・プレリリース || 公開前のドラフト状態での準備や安定版に先立つプレリリース版の公開に対応している。
|}
</center>
<br>
Releaseはタグと区別して管理されており、タグのみが存在する状態と、タグにReleaseを付与した状態は異なる扱いとなる。<br>
<br><br>

== Gitタグ ==
==== タグとは ====
Gitタグは、リポジトリ履歴の特定コミットを指し示すための参照である。<br>
<br>
タグはバージョンのマーキングに使用され、後から特定のバージョンに容易にアクセスできるようにする。<br>
<br>
タグの一覧を確認するコマンドを以下に示す。<br>
<br>
 # 全タグの一覧表示
 git tag
 
 # パターンに一致するタグの一覧表示
 git tag -l "v1.*"
<br>
特定タグの詳細情報を確認するコマンドを以下に示す。<br>
<br>
 git show v1.4
<br>
==== 軽量タグとアノテーションタグ ====
Gitタグには軽量タグとアノテーションタグの2種類が存在する。<br>
<br>
下表に、2種類のタグの違いを示す。<br>
<br>
<center>
{| class="wikitable"
|+ 軽量タグとアノテーションタグの比較
! 項目 !! 軽量タグ !! アノテーションタグ
|-
| データ構造 || コミットへのポインタのみ || 完全なGitオブジェクト
|-
| メタデータ || なし || タッガー名、メールアドレス、日時、メッセージ
|-
| GPG 署名 || 不可 || 可能
|-
| リモートへの転送 || されない || される
|-
| 主な用途 || 一時的・内部的な目的 || 公開リリース
|}
</center>
<br>
<u>公開リリースにはアノテーションタグを使用することが推奨される。</u><br>
<br>
==== タグの作成 ====
アノテーションタグを作成するコマンドを以下に示す。<br>
<br>
 git tag -a v1.4 -m "バージョン 1.4 リリース"
<br>
軽量タグを作成するコマンドを以下に示す。<br>
<br>
 git tag v1.4-lw
<br>
過去のコミットにタグを付ける場合は、コミットのチェックサム (または一部) を指定する。<br>
<br>
 # コミット履歴を確認してチェックサムを取得する
 git log --oneline
 
 # 過去コミットへのタグ付け
 git tag -a v1.2 9fceb02 -m "バージョン 1.2 リリース"
<br>
==== タグのプッシュ ====
<code>git push</code> コマンドは、デフォルトではタグをリモートリポジトリに転送しない。<br>
<br>
<u>タグを明示的にプッシュする必要がある。</u><br>
<br>
* 特定のタグをプッシュするコマンド
*: <pre>git push origin v1.4</pre>
*: <br>
* 全てのタグを一括でプッシュするコマンド
*: <pre>git push --tags</pre>
<br>
<code>--tags</code> オプションは軽量タグとアノテーションタグの両方を転送する。<br>
<br>
アノテーションタグのみを転送する場合は <code>--follow-tags</code> オプションを使用する。<br>
<br>
==== タグの削除 ====
ローカルのタグを削除するコマンドを以下に示す。<br>
<br>
 git tag -d v1.2.0
<br>
リモートリポジトリのタグを削除するコマンドを以下に示す。<br>
<br>
 git push origin --delete tag v1.2.0
<br>
リモートタグを削除しても、ローカルのタグは残るため、ローカルとリモートの両方で削除操作が必要である。<br>
<br><br>

== Releaseの作成 ==
==== Web UIでの作成 ====
GitHubのWebインターフェースからReleaseを作成する手順を以下に示す。<br>
<br>
# リポジトリのトップページで[Releases]を選択する。
# [Draft a new release]ボタンを押下する。
# [Choose a tag]ドロップダウンから既存のタグを選択するか、新しいタグ名を入力して[Create new tag]を選択する。
# [Target]ドロップダウンから、タグを付けるブランチまたはコミットを選択する。
# [Release title]フィールドにリリースのタイトルを入力する。
# 説明欄にリリースノートを入力する。
# 必要に応じてバイナリファイルをドラッグ&ドロップでアセットとして添付する。
# プレリリースの場合は、[Set as a pre-release]チェックボックスにチェックを入力する。
# [Publish release]ボタンを押下してリリースを公開する。
<br>
==== GitHub CLIでの作成 ====
GitHub CLIを使用すると、コマンドからReleaseを作成できる。<br>
<br>
基本的な作成コマンドを以下に示す。<br>
<br>
 gh release create v1.0.0 --title "v1.0.0" --notes "リリースノートの内容"
<br>
ファイルをアセットとして添付する場合のコマンドを以下に示す。<br>
<br>
 gh release create v1.0.0 ./dist/app-linux ./dist/app-windows.exe \
    --title "v1.0.0" \
    --notes "リリースノートの内容"
<br>
下表に、主要なオプションを示す。<br>
<br>
<center>
{| class="wikitable"
|+ gh release createオプション一覧
! オプション !! 説明
|-
| <code>--title</code> || Releaseのタイトルを指定する。
|-
| <code>--notes</code> || リリースノートのテキストを指定する。
|-
| <code>--notes-file</code> || リリースノートをファイルから読み込む。
|-
| <code>--generate-notes</code> || リリースノートを自動生成する。
|-
| <code>--target</code> || タグを付けるブランチまたはコミットを指定する。
|-
| <code>-d</code> || ドラフト状態で作成する。
|-
| <code>-p</code> || プレリリースとしてマークする。
|-
| <code>--latest</code> || 最新リリースとしてマークする。
|}
</center>
<br>
==== プレリリース ====
プレリリースは、安定版の前に公開するテスト段階のリリースである。<br>
<br>
Web UIでは[Set as a pre-release]チェックボックスにチェックを入力することにより、プレリリースとして設定できる。<br>
<br>
GitHub CLI でプレリリースを作成するコマンドを以下に示す。<br>
<br>
 gh release create v1.0.0-beta.1 -p --title "v1.0.0-beta.1" --notes "ベータ版リリース"
<br>
プレリリースは "Latest release" としては表示されず、Releasesページ上で "Pre-release" ラベルが付与される。<br>
<br>
==== ドラフトリリース ====
ドラフトリリースは、公開前の準備段階として保存するリリースである。<br>
<br>
ドラフト状態ではReleaseは一般ユーザには見えず、リポジトリの管理者のみが参照できる。<br>
<br>
GitHub CLIでドラフトリリースを作成するコマンドを以下に示す。<br>
<br>
 gh release create v1.0.0 -d --title "v1.0.0" --notes "リリースノートの内容"
<br>
ドラフトは後から編集して公開 (Publish) することができる。<br>
<br><br>

== リリースノート ==
==== リリースノートの自動生成 ====
GitHubには、マージ済みのプルリクエストとコントリビュータを自動的にまとめてリリースノートを生成する機能がある。<br>
<br>
Web UIで自動生成するには、Release作成画面の説明欄上部にある[Generate release notes]ボタンを押下する。<br>
前回のReleaseタグ以降のマージ済みPRと新しいコントリビュータが自動的にまとめられる。<br>
<br>
GitHub CLIで自動生成するコマンドを以下に示す。<br>
<br>
 gh release create v1.0.0 --generate-notes
<br>
==== release.ymlの設定 ====
<u>.github/release.yml</u> ファイルを作成することにより、自動生成されるリリースノートの内容をカスタマイズできる。<br>
<br>
設定ファイルの基本的な構成例を以下に示す。<br>
<br>
 <syntaxhighlight lang="yaml">
 changelog:
    exclude:
       labels:
          - ignore-for-release
          - dependencies
       authors:
          - dependabot
    categories:
       - title: 破壊的変更
         labels:
            - breaking-change
       - title: 新機能
         labels:
            - feature
            - enhancement
       - title: バグ修正
         labels:
            - bug
            - fix
       - title: その他の変更
         labels:
            - '*'
 </syntaxhighlight>
<br>
下表に、release.ymlファイルの主要な設定項目を示す。<br>
<br>
<center>
{| class="wikitable"
|+ release.ymlファイルの主な設定項目一覧
|-
! 設定項目 !! 説明
|-
| <code>changelog.exclude.labels</code> || 指定したラベルが付いたPRをリリースノートから除外する。
|-
| <code>changelog.exclude.authors</code> || 指定した作成者のPRを除外する。<br><code>dependabot</code> 等の自動化ツールを除外する時に使用する。
|-
| <code>changelog.categories</code> || PRをカテゴリに分類して表示する。<br><code>title</code> にカテゴリ名、<code>labels</code> に対象ラベルを指定する。
|-
| ワイルドカード <code>'*'</code> || いずれのカテゴリにも該当しないPRを全てキャッチするために使用する。
|}
</center>
<br>
==== コントリビュータの自動表示 ====
リリースノートの自動生成では、対象期間内に初めてコントリビュートしたユーザが <u>New Contributors</u> として自動的にリストアップされる。<br>
<br>
この機能により、コントリビュータへの感謝を示すセクションが自動的に追加される。<br>
<br><br>

== Releaseの管理 ==
==== Releaseの編集 ====
公開済みのReleaseは後から編集できる。<br>
<br>
Web UIでの編集手順を以下に示す。<br>
<br>
# [Releases]ページで編集するReleaseの鉛筆アイコンを選択する。
# タイトル、説明、アセット、プレリリース設定等を変更する。
# [Update release]ボタンを押下して、保存する。
<br>
GitHub CLIでReleaseを編集するコマンドを以下に示す。<br>
<br>
 gh release edit v1.0.0 --title "新しいタイトル" --notes "更新されたリリースノート"
<br>
==== Releaseの削除 ====
Web UIでの削除手順を以下に示す。<br>
<br>
# [Releases]ページで削除するReleaseのゴミ箱アイコンを選択する。
# 確認ダイアログにおいて、[Delete]を選択する。
<br>
GitHub CLIでReleaseを削除するコマンドを以下に示す。<br>
<br>
 # Releaseのみを削除する (タグは残る)
 gh release delete v1.0.0
 
 # Releaseと関連するタグを同時に削除する
 gh release delete v1.0.0 --cleanup-tag
<br>
Releaseを削除しても、デフォルトでは関連するGitタグは削除されない。<br>
タグも合わせて削除する場合は <code>--cleanup-tag</code> オプションを使用する。<br>
<br>
==== ドラフトの公開 ====
ドラフト状態のReleaseを公開するには、Web UI または GitHub CLI を使用する。<br>
<br>
GitHub CLIでドラフトを公開するコマンドを以下に示す。<br>
<br>
 gh release edit v1.0.0 -d=false
<br><br>

== アセット管理 ==
==== バイナリファイルの添付 ====
Releaseにはコンパイル済みバイナリ等の任意のファイルをアセットとして添付できる。<br>
<br>
Web UIでアセットを添付する手順を以下に示す。<br>
<br>
# Releaseの作成画面または編集画面を開く。
# [Attach binaries by dropping them here or selecting them.]のエリアにファイルをドラッグ&ドロップ、または、クリックしてファイルを選択する。
<br>
GitHub CLIでアセットを添付する場合は、<code>gh release create</code> コマンドの引数にファイルパスを指定する。<br>
<br>
 gh release create v1.0.0 \
    ./dist/app-linux-amd64 \
    ./dist/app-windows-amd64.exe \
    ./dist/app-darwin-amd64
<br>
==== ソースコードアーカイブ ====
GitHubは全てのReleaseに対して、ソースコードのZIPアーカイブとtar.gzアーカイブを自動的に生成して添付する。<br>
これらのアーカイブは手動での操作なしに提供され、ReleaseページのAssetsセクションに表示される。<br>
<br>
* <u>Source code (zip)</u>
*: ソースコードのZIP形式アーカイブ
* <u>Source code (tar.gz)</u>
*: ソースコードのtar.gz形式アーカイブ
<br>
==== アセットの制限 ====
Releaseに添付できるアセットには以下に示す制限がある。<br>
<br>
<center>
{| class="wikitable"
|+ アセットの制限
! 項目 !! 制限値
|-
| 1 リリースあたりの最大アセット数 || 1000ファイル
|-
| 1 ファイルあたりの最大サイズ || 2[GiB]
|-
| 総サイズ || 無制限
|-
| 帯域幅 || 無制限
|}
</center>
<br>
==== アセットの表示ラベル ====
アセットに任意の表示名 (ラベル) を付加することができる。<br>
<br>
GitHub CLIでラベルを付けてアセットを添付するコマンドを以下に示す。<br>
<code>#</code> 以降の文字列がラベルとして表示される。<br>
<br>
 gh release create v1.2.3 \
    '/path/to/app.exe#App for Windows' \
    '/path/to/app-linux#App for Linux'
<br><br>

== セマンティックバージョニング ==
==== バージョン番号の形式 ====
セマンティックバージョニングは、バージョン番号に意味を持たせるための標準的な規則である。<br>
バージョン番号は <u>X.Y.Z</u> の形式で表記する。<br>
<br>
下表に、それぞれの要素の意味を示す。<br>
<br>
<center>
{| class="wikitable"
|+ バージョン番号の要素
! 要素 !! 名称 !! 増加するタイミング
|-
| X || Major (メジャー) || 後方互換性のない破壊的変更を行った場合
|-
| Y || Minor (マイナー) || 後方互換性を保ちながら機能を追加した場合
|-
| Z || Patch (パッチ) || 後方互換性を保ちながらバグ修正を行った場合
|}
</center>
<br>
各要素の先頭にゼロを付けてはならない。<br>
例えば、<u>1.01.0</u> は無効な表記である。<br>
<br>
==== タグの命名規則 ====
GitHubでの一般的なタグの命名規則を以下に示す。<br>
<br>
* <u>v1.0.0</u>
*: 最も一般的な形式
*: 先頭の <u>v</u> はオプションだが慣習として広く使われている。
* <u>v1.0.0-alpha</u>
*: アルファ版
*: 機能が未完成の段階のプレリリース
* <u>v1.0.0-beta</u>
*: ベータ版
*: 機能は完成しているが、テスト段階のプレリリース
* <u>v1.0.0-rc.1</u>
*: リリース候補 (Release Candidate)
*: 最終リリース前の最終テスト段階
<br>
プレリリースバージョンはハイフン区切りで識別子を付与する。<br>
先頭の <u>v</u> はオプションであるが、プロジェクト内で統一することが推奨される。<br>
<br><br>

== GitHub CLIでのRelease操作 ==
==== gh release list ====
リポジトリのRelease一覧を表示するコマンドを以下に示す。<br>
<br>
 # Releaseの一覧を表示する
 gh release list
 
 # ドラフトを除外して表示する
 gh release list --exclude-drafts
 
 # プレリリースを除外して表示する
 gh release list --exclude-pre-releases
 
 # 表示件数を指定する (デフォルト: 30)
 gh release list -L 10
 
 # JSON形式で出力する
 gh release list --json tagName,name,isDraft,isPrerelease,publishedAt
<br>
==== gh release view ====
特定のReleaseの詳細情報を表示するコマンドを以下に示す。<br>
<br>
 # 特定タグのReleaseを表示する
 gh release view v1.0.0
 
 # 最新のReleaseを表示する
 gh release view
 
 # Webブラウザで開く
 gh release view v1.0.0 -w
 
 # JSON 形式で出力する
 gh release view v1.0.0 --json tagName,name,body,assets
<br>
==== gh release download ====
Releaseのアセットをダウンロードするコマンドを以下に示す。<br>
<br>
 # 特定タグの全アセットをダウンロードする
 gh release download v1.0.0
 
 # パターンに一致するアセットのみをダウンロードする
 gh release download v1.0.0 --pattern "*.zip"
 
 # ソースコードアーカイブをダウンロードする
 gh release download v1.0.0 --archive=zip
 gh release download v1.0.0 --archive=tar.gz
 
 # ダウンロード先ディレクトリを指定する
 gh release download v1.0.0 -D ./downloads
 
 # 既存ファイルを上書きする
 gh release download v1.0.0 --clobber
 
 # 既存ファイルをスキップする
 gh release download v1.0.0 --skip-existing
<br>
==== gh release edit ====
既存のReleaseを編集するコマンドを以下に示す。<br>
<br>
 # タイトルを変更する
 gh release edit v1.0.0 --title "新しいタイトル"
 
 # リリースノートを変更する
 gh release edit v1.0.0 --notes "更新されたリリースノート"
 
 # プレリリースとしてマークする
 gh release edit v1.0.0 -p
 
 # ドラフト状態を解除して公開する
 gh release edit v1.0.0 -d=false
<br>
==== gh release delete ====
Releaseを削除するコマンドを以下に示す。<br>
<br>
 # Releaseを削除する (タグは残る)
 gh release delete v1.0.0
 
 # Releaseと関連するタグを同時に削除する
 gh release delete v1.0.0 --cleanup-tag
 
 # 確認プロンプトをスキップして削除する
 gh release delete v1.0.0 -y
<br><br>

== Releaseの通知 ==
==== ウォッチ設定 ====
リポジトリの新しいReleaseが公開された際に通知を受け取るには、リポジトリのウォッチ設定を変更する。<br>
<br>
設定手順を以下に示す。<br>
<br>
# リポジトリのページ上部にある[Watch]ボタンを押下する。
# ドロップダウンメニューから[Custom]を選択する。
# [Releases]チェックボックスをオンにする。
# [Apply]ボタンを押下して、設定を保存する。
<br>
この設定により、新しいReleaseが公開された時に、GitHubの通知センターおよびメールで通知を受け取ることができる。<br>
<br>
==== RSS / Atomフィード ====
GitHub ReleasesはRSS / Atomフィードを提供しており、RSSリーダー等を使用して新しいReleaseを購読できる。<br>
<br>
* フィードのURLの形式
*: https://github.com/<owner>/<repo>/releases.atom
<br>
<code>&lt;owner&gt;</code> にはリポジトリオーナーのユーザ名または組織名、<code>&lt;repo&gt;</code> にはリポジトリ名を指定する。<br>
<br>
フィードの具体的な使用例を以下に示す。<br>
<br>
 # 例: curlでReleasesフィードを取得する
 curl https://github.com/octocat/Hello-World/releases.atom
<br><br>


{{#seo:
|title={{PAGENAME}} : Exploring Electronics and SUSE Linux | MochiuWiki
|keywords=MochiuWiki,Mochiu,Wiki,Mochiu Wiki,Electric Circuit,Electric,pcb,Mathematics,AVR,TI,STMicro,AVR,ATmega,MSP430,STM,Arduino,Xilinx,FPGA,Verilog,HDL,PinePhone,Pine Phone,Raspberry,Raspberry Pi,C,C++,C#,Qt,Qml,MFC,Shell,Bash,Zsh,Fish,SUSE,SLE,Suse Enterprise,Suse Linux,openSUSE,open SUSE,Leap,Linux,uCLnux,電気回路,電子回路,基板,プリント基板
|description={{PAGENAME}} - 電子回路とSUSE Linuxに関する情報 | This page is {{PAGENAME}} in our wiki about electronic circuits and SUSE Linux
|image=/resources/assets/MochiuLogo_Single_Blue.png
}}

__FORCETOC__
[[カテゴリ:Git]]