====== GitHub ソースコードの公開 ====== --- //[[http://www.y2sunlight.com|y2sunlight]] 2020-07-03// [[github:top|GitHub に戻る]] 本章では、GitHubによってオープンソースを公開するまでを筆者の体験を基に掲載します。 オープンソースとして公開するアプリケーションは、本編でその製作過程の説明をした[[apricot:top|Apricot]]です。Apricotは「ちょっとしたアプリ」を作成する為の非パッケージ型のミニ・フレームワークです（本編では、これを「[[sampleproj:#ステイプルワーク|ステイプルワーク]]」と呼んでいます）。Apricotは通常のフレームワークのようにパッケージの形態を取っていないのでコア・コードを直接自由にカスタマイズして使用できます。 本章の内容は、[[github:config|GitHubのアカウントの取得]]と以下のクライアント環境を前提条件としています。Gitクライアントには[[git2:client:windows:eclipse|Eclipse( EGitプラグイン )]]を使用します。 クライアント環境 * Windows10 Pro 64bits * XAMPP 7.3.15 * PHP 7.3.15 (VC15 X86 64bit thread safe) * Eclipse 2019-12 Version 4.14 * Composer 1.10.1 関連記事 * [[github:config|GitHub 環境構築]] * [[github:email|GitHub メールの設定]] * [[github:profile|GitHub プロフィールの設定]] * [[github:basic|GitHub Eclipseによるリポジトリの基本操作]] * [[github:branch|GitHub Eclipseによるブランチの操作]] * [[github:release|GitHub タグとリリースの作成]] * [[github:collaborator|GitHub コラボレータの招待]] * GitHub ソースコードの公開 リンク * https://github.com/ --- GitHubの本家 * https://guides.github.com/ --- GitHubガイド * https://help.github.com/ja/github/ --- GitHubヘルプ GitHub * [[https://github.com/y2sunlight/apricot/|y2sunlight/apricot]] --- リポジトリはGitHubで公開しています ---- ===== 概要 ===== 本章で公開するプロジェクトの概要を示します。 === プロジェクト(Eclipse) === |プロジェクト名|apricot| |ラインセンス|[[https://ja.wikipedia.org/wiki/MIT_License|MIT LICENSE]]| |ワークスペース|D:\usr\github\y2sunlight| === リモートリポジトリ(GitHub) === |リポジトリ名|apricot| |リポジトリURL|https://github.com/y2sunlight/apricot.git| === ブランチ === * リモートブランチ * master --- デフォルトブランチ。初版リリースまではここで作業する * readme-edits --- README.md, LICENSEファイルの編集用 * ローカルブランチ * master * readme-edits === ソースファイル構成 === * アプリケーションファイル一式 --- フォルダ構成は本編の「[[apricot:top|Apricot]]」を参照 * README.md --- Installation, Quick Start等を記載。使用法はWikiに記載する * LICENSE --- ライセンスファイル === 公開までの手順 === * [[#リポジトリを準備する]] * [[#リポジトリの作成]] * [[#リポジトリについての設定]] * [[#ブランチの作成]] * [[#コラボレータの招待]] * [[#Eclipse ワークスペースの準備]] * [[#Eclipse プロジェクトの作成]] * [[#ソースコードの準備をする]] * [[#ソースコードの配置]] * [[#composerの設置]] * [[#composer.jsonの作成]] * [[#リリースの準備をする]] * [[#ソースコード]] * [[#README.md]] * [[#LICENSE]] * [[#プレリリースする]] * [[#ドキュメントを作る(Wiki)]] * [[#本番リリースする]] \\ ===== リポジトリを準備する ===== 新しく、公開用のリポジトリ ''apricot'' を作成し、初版のリリースの準備を行います。 ==== リポジトリの作成 ==== 画面右上の[+]メニューから[New repository]を選択して下さい。 [{{:github:publish:github-publish01.png?nolink|}}] ■ 必要な項目を入力します。 * [Repository name] --- リポジトリ名(ここでは ''apricot'' ) を入力します。 * [Description] --- 短い説明文を入力できます。 * [Public]/[Private] --- Publicを選択するとリポジトリがインターネットに公開されます。 * [Initialize this repository with a README] --- READMEでこのリポジトリを初期化します。 * [その他] * ''.gitignore'' --- 本章では .gitignore を独自で作成すので ''None'' を選択します。 * ''License'' --- apricotは ''MIT License'' で公開するします。 ■ [Create]ボタンを押して下さい。 \\ ==== リポジトリについての設定 ==== リポジトリ apricot の画面を表示します。 [{{:github:publish:github-publish03.png?nolink|}}] ■ [About]右横の歯車アイコンをクリックして下さい。 [{{:github:publish:github-publish04.png?nolink|}}] ■ [Description], [Website], [Topics]を編集します。 \\ ■ [Include in the home page]で必要なものにチェックを入れます。 \\ ■ [Save changes]ボタンを押して下さい。 \\ ==== ブランチの作成 ==== リポジトリ apricot の画面を表示します。 [{{:github:publish:github-publish06.png?nolink|}}] ■ ファイルリスト上部のドロップダウン[branch：master] をクリックします。\\ ■ テキストボックスに 新しいブランチのブランチ名 ''readme-edits'' を入力します。\\ ■ [Branches]内の[**Create branch: readme-edits** from 'master']を選択して下さい。 \\ ==== コラボレータの招待 ==== プロジェクトに参加してもらえる開発者をコラボレータとして招待します。詳細は「[[#github:collaborator|コラボレータの招待]]」を参照して下さい。 リポジトリ画面の[Settings]タブを選択した後、左サイドバーで[Manage access]を選択します。 [{{:github:publish:github-publish08.png?nolink|}}] ■ 右の緑色の[Invite a collaborator]ボタンを押します。\\ [{{:github:publish:github-publish09.png?nolink|}}] ■ 招待するコラボレータのユーザ名を入力します(フルネームやメールアドレスでも可)。\\ ■ 検索結果が表示されるので、目的の人を選択します。\\ ■ [Add {ユーザ名} to {リポジトリ名}]ボタンを押して下さい。 \\ ===== Eclipse ワークスペースの準備 ===== ==== ワークスペースの作成 ===== 本編では、ワークスペースを以下に作成します。 D:\\usr\github\y2sunlight \\ ==== Apacheの設定 ===== httpd.confの末尾に以下の内容を追加します。 {{fa>file-o}} ''{XAMPP Install Folder}\apache\conf\y2sunlight.conf'' # My project settings Include conf/my-extra/*.conf 新しく、以下のフォルダを作成し、 {XAMPP Install Folder}\apache\conf\my-extra その中に以下の内容で、ファイル(y2sunlight.conf)を作成します。 Alias /y2sunlight "D:/usr/github/y2sunlight" Options All AllowOverride All Require all granted Apacheを再起動します。 \\ ==== ワークスペースの設定 ===== Eclipseを起動しワークスペース(D:\usr\github\y2sunlight)を開きます。 Eclipseの初期設定方法については、本編「Eclipse 2019-12のインストール」の[[eclipse:2019-12#ワークスペースの設定|ワークスペースの設定]]を参照して下さい。 \\ ===== Eclipse プロジェクトの作成 ===== ==== Eclipse プロジェクトのインポート ==== GitHubのリモートリポジトリ( apricot ) の master ブランチをインポートして Eclipseで編集できるようにします。操作方法については概略のみ説明します。詳細は、本編の「[[github:basic#プロジェクトのインポート|GitHub Eclipseによるリポジトリの基本操作]]」を参照して下さい。 以下をプロジェクトフォルダに指定します。 D:\\usr\github\y2sunlight\apricot Eclipseを起動して、次の手順で作業を進めます。 * メニューから[ファイル][インポート]を選択します。\\ * [Git][Gitプロジェクト]を選択し、[次へ]を押します。\\ * [クローンURI]を選択し、[次へ]を押します。 \\ [{{:github:publish:github-publish12.png?nolink|}}] ■ [URI]を入力します。\\ ここでは ''https://github.com/y2sunlight/apricot.git'' を入力します。\\ ■ URIを入力するとそれに応じて他の項目は自動で表示されます。\\ ■ 認証情報は必要に応じて入力して下さい。\\ ■ [次へ]を押します。 [{{:github:publish:github-publish13.png?nolink|}}] ■ ブランチ ''master'' と ''readme-edits'' の両方にチェックを入れます。\\ ■ [次へ]を押します。 [{{:github:publish:github-publish14.png?nolink|}}] ■ ローカルリポジトリの保存先にはワークスペース下のプロジェクトフォルダを指定します。\\ ここでは ''D:\usr\github\y2sunlight\apricot'' を指定します。\\ ■ 初期ブランチに ''master'' を選択します。\\ ■ [次へ]を押します。 [{{:github:publish:github-publish15.png?nolink|}}] ■ [新規プロジェクト・ウイザードを使用してインポート]を選択して、[完了]を押します。 [{{:github:publish:github-publish16.png?nolink|}}] ■ [PHPプロジェクト]を選択して、[次へ]を押します。\\ ■ PHPプロジェクトの作成画面で [プロジェクト名]に ''apricot'' を入力して、[完了]を押します。 ==== GitHubのメールとユーザ名の設定 ==== GitHubからプロジェクトをインポートした後、まず最初にしなければならない事は、コミットメールアドレスの変更です。GitHub用のメールアドレスを設定しないとユーザ共通のメールアドレスが使用されます。ユーザ名の変更は必要に応じて行って下さい。 Eclipse で ''apricot'' リポジトリの設定画面を開きます： - メニューの[ウインドウ][設定]を選択 - 左ペインで[チーム][Git][構成]を選択 - 右ペインの[構成]から[リポジトリ設定]を選択 - [リポジトリ]で[apricot]を選択 [{{:github:publish:github-publish17.png?nolink|}}] ■ [エントリー追加...]ボタンを押します。\\ ■ 以下の項目を必要に応じて追加して下さい。
- ユーザ名（キー： ''user.name''） - メールアドレス（キー： ''user.email''）
■ [適用]ボタンを押します。 \\ ==== その他のEclipseの設定 ==== ApricotではComposerを使用するので、プロジェクトにComposerのファセットを追加しておきます。 - プロジェクトを右クリック[プロパティー]をクリックします。 - [プロジェクト・ファセット][Composer]にチェックを入れ、[適用して閉じる]をクリックします。 その他は、以下を参照して設定を行って下さい。 * [[eclipse:2019-12#プロジェクト・エクスプローラーの設定]] * [[eclipse:2019-12#デフォルト・ベースURLの設定]] \\ (ベース・パスは''/y2sunlight/apricot''に設定して下さい) \\ ===== ソースコードの準備をする ===== GitHubに公開する初版となるソースコードを準備します。メインとなるソースコードは、本編の「[[apricot:top|Apricot]]」で掲載したソースコード一式です。ここでは、そのソースコードを先に[[#Eclipse プロジェクトの作成|作成]]したプロジェクトに配置し、外部ライブラリーを再取得して、公開用の''composer.json'' を作成します。 プロジェクトフォルダGitHubへの公開で不要な（環境依存している）プロジェクト関連のファイルと、実行時に作成されるフォルダやファイルを無視ファイルとして.gitignoreファイルに登録します。また、環境設定ファイルのサンプル( ''.env.sample'' )を 公開用に作成します。 ソースコードの準備ができたら、準備したこれらのファイルをリポートブランチ(''master'')にプッシュします。 \\ ==== ソースコードの配置 ==== Apricotフォルダの内、以下に示したのフォルダまたはファイルをプロジェクトフォルダに配置します。 apricot [プロジェクトルート] | ├── app/ ・・・ アプリケーション ├── assets/ ・・・ リソースファイル ├── config/ ・・・ 設定ファイル ├── core/ ・・・ コア ├── public/ ・・・ 公開フォルダ ├── var/ ・・・ データフォルダ └── .env ・・・ 環境設定ファイル 全てのフォルダの構成は本編「Apricot プロジェクトの作成」の[[apricot:configuration#フォルダ構成|]]フォルダ構成 を参照して下さい。 \\ ==== Composer.jsonの作成 ==== まず、プロジェクトフォルダ直下で、コマンド ''composer init'' を実行して ''composer.json'' を初期化します。コマンドの途中で、以下のように質問に答えます。但し、''require'' と ''require-dev'' の項目は後で手動で追加します。 {{tablelayout?colwidth="150px"}} ^Package name|y2sunlight/apricot| ^Description|Apricot is a PHP mini-framework (non-packaged version) for quickly creating simple applications.| ^Author|Yoshihiro Iwata | ^Package Type|project| ^License|MIT| コマンドが終わると、プロジェクトフォルダ内に ''composer.json'' を作成されます。 次に、自動再生された ''composer.json'' に、''require'' と ''autoload'' などの項目を必要に応じて追加します。 {{fa>folder-open-o}} ** apricot/ ** { "name": "y2sunlight/apricot", "type": "project", "description": "Apricot is a PHP mini-framework (non-packaged version) for quickly creating simple applications.", "keywords": ["php","framework","mini","non-packaged"], "homepage": "http://y2sunlight.com/ground/doku.php?id=apricot:top", "license": "MIT", "authors": [ { "name": "Yoshihiro Iwata", "email": "github@y2sunlight.com", "homepage": "http://y2sunlight.com" } ], "require": { "php": "^7.3" }, "autoload" : { "psr-4" : { "App\\" : "app/", "Apricot\\" : "core/" }, "files": [ "core/helpers/utilities.php", "core/helpers/boilerplates.php" ] } } * ''require'' には、インストールする外部ライブラリのPHPバージョンのみを指定します。\\ 実際の外部ライブラリの指定は、この後、コマンド ''composer require'' を使って追加していきます。 * ''autoload.psr-4''には、Apricotの名前空間を指定します。''App\'' は、ローカルな名前空間で、Aprocotのアプリケーションを配置します。一方、''Y2sunlight\Apricot\'' は、GitHubの ''{ユーザ名(ベンダー名)}/{リポジトリ名}'' に基づくグローバルな名前空間で、Apricotのコア部分（本来、ライブラリーになる部分）を配置します。 * ''autoload.files''には、オートローディングするヘルパー関数などを指定しておきます。 \\ ==== 外部ライブラリーの設置 ==== Apricotでは以下の外部ライブラリーを使用しています。 ^機能^パッケージ名^Vsersion^Level^License^ |環境変数|[[https://github.com/vlucas/phpdotenv|phpdotenv]]|5.0|Core|BSD 3-Clause| |ログ出力|[[https://github.com/Seldaek/monolog|monolog]]|2.1|Core|MIT| |リクエストルーター|[[https://github.com/nikic/FastRoute|FastRoute]]|1.3|Core|Similar to BSD 3-Clause| |DIコンテナー|[[https://github.com/thephpleague/container|League/Container]]|3.3|Core|MIT| |テンプレートエンジン|[[https://github.com/EFTEC/BladeOne|BladeOne]]|3.46|Core|MIT| |エラーハンドラー|[[https://github.com/filp/whoops|Whoops]]|2.7|Core|MIT| |デバッグ出力|[[https://github.com/maximebf/php-debugbar|php-debugbar]]|1.16|Core|MIT| |アセット管理|[[https://github.com/kriswallsmith/assetic|assetic]]|1.4|Core|MIT| |ORマッパー|[[https://github.com/j4mie/idiorm|idiorm]]|1.5|App|BSD| |バリデーター|[[https://github.com/vlucas/valitron|Valitron]]|1.4|App|BSD 3-Clause| > ''assetic'' は ''php-debugbar''のアセット読み込みで使用するために追加しました。
Levelについて * Core --- Apricotのコアで使用するライブラリー * App --- Apricotのアプリで使用するライブラリー
上記の外部ライブラリーをコマンド ''composer require'' を使って取得すると同時に、''composer.json'' を書き換えます。 composer require vlucas/phpdotenv composer require monolog/monolog composer require nikic/fast-route composer require league/container composer require eftec/bladeone composer require filp/whoops composer require maximebf/debugbar composer require kriswallsmith/assetic composer require j4mie/idiorm composer require vlucas/valitron 全ての外部ライブラリーの取得が終了すると、''composer.json'' は以下のように書き換わります。 { .... "require": { "php": "^7.3", "vlucas/phpdotenv": "^5.0", "monolog/monolog": "^2.1", "nikic/fast-route": "^1.3", "league/container": "^3.3", "eftec/bladeone": "^3.46", "filp/whoops": "^2.7", "maximebf/debugbar": "^1.16", "kriswallsmith/assetic": "^1.4", "j4mie/idiorm": "^1.5", "vlucas/valitron": "^1.4" }, .... } ここまでの作業が終わると、新しく以下のファイル(またはフォルダ)が追加されます。 * ''composer.json'' --- composerの依存関係の定義ファイル * ''composer.lock'' --- 実際にダウンロードした外部ライブラリのバージョン定義ファイル * ''vendor/'' --- 実際にダウンロードした外部ライブラリ この中で、公開に必要なものは、''composer.json'' だけです。他は、後で説明する、.gitignore ファイルに指定して、リモートリリポジトリにプッシュしないようにします。 \\ ==== .gitignoreファイルの作成 ==== プロジェクトフォルダ直下に以下の ''.gitignore'' を設置します。 {{fa>folder-open-o}} ** apricot/ ** /.settings/ /.buildpath /.project /composer.lock /vendor/ /.env * ''/.settings/'' , ''/.buildpath'' , ''/.project'' はEclipseのプロジェクト関連ファイルです。 * ''/composer.lock'' は composerのロックファイルで、''/vendor/'' は外部ライブラリの保存フォルダです。 * ''/.env'' はApricotの環境設定ファイルです。 Apricotの以下のデータフォルダに''.gitignore'' を設置します。
* ''apricot/public/var/'' * ''apricot/var/cache/'' * ''apricot/var/db/'' * ''apricot/var/logs/''
* !.gitignore \\ ==== 環境設定ファイルのサンプル作成 ==== 公開用の環境設定ファイルのサンプル( .env.sample )を、プトジェクトフォルダ直下に作成します。 {{fa>folder-open-o}} ** apricot/ ** # Application APP_NAME=Apricot APP_VERSION=1.0.0 #APP_SECRET=Please set a random 32 characters APP_SECRET=0123456789ABCEDF0123456789ABCEDF APP_DEBUG=true APP_TIMEZONE=Asia/Tokyo APP_LANG=ja # Loging LOG_NAME ="apricot" LOG_LEVEL = "debug" \\ ==== 最初のプッシュ ==== 最初にプッシュするソースコードの準備がでたら、まずはローカルブランチ(''master'')にコミットします。 [{{:github:publish:github-publish19.png?nolink|}}] ■ 無視ファイル以外の全てのファイルをステージして、[コミット]します。 コミットが終了したらプロジェクト・エクスプローラで、apricotを選択して[チーム][アップストリームへプッシュ]します。 GitHubのリポジトリ apricot の画面を表示します。 [{{:github:publish:github-publish20.png?nolink|}}] ■ プッシュしたソースコードを確認します。 \\ ===== リリースの準備をする ===== ここでの作業は次の３つです。 * Apricot本体のリファクタリング * REAMME.mdファイルの編集 * LICENSEファイルの編集 Apricot本体のリファクタリング作業は、最初に本番リリースするまでは master ブランチで行い、REAMME.mdファイルとLICENSEファイルの編集作業は、別のreadme-editsブランチで行います。 \\ ==== ソースコード ==== GitHubでソースコードを公開するに当たって、以下のリファクタリングを行いました。リファクタリングの中心は名前空間の変更と英語化になります。「日本語のままでもいいかな...」と思いつつも、機械翻訳に頼って英語化しました。 * 名前空間の変更 --- Apricotコアの名前空間を Core から Apricot に変更 * 国際化 --- 英語のリソースを追加 * コメントの英語化 また、外部ライブラリーが使用しているアセット(CSSとJs)の取り込みを手動でなく自動で出来るように、アセット管理フレームワーク [[https://github.com/kriswallsmith/assetic|Assetic]] を追加しました。その他、細かい点も修正しています。 GitHub公開している[[https://github.com/y2sunlight/hello-world|Apricot(V1.0)]]と本編で掲載している[[apricot:top|Apricot(0.9)]]は、異なったバージョンです。 \\ ==== README.mdファイル ==== 公開するソースコードのドキュメントは必須です。使い方の分からないソースコードは意味がありません。REAMME.mdの書き方は様々ですが、最低限必要なものは、概要、インストール方法とライセンスだと思います。Apricotでは、これらに加えて、クイックスタートを書き足し、詳しい使用方法はREAMME以外で(GitHubのWiki または 当サイト)で公開する事にしました。 \\ ==== LICENSEファイル ==== GitHubでは、リポジトリ作成時にLICENSEファイルの雛形が準備されているので、ライセンスの作成がとても簡単にできます。ライセンスを明記しなかった場合は、[[https://choosealicense.com/no-permission/|No License]]という扱いになり、利用者には複製、再頒布、改変が認められません。 Apricotは、公開を目的としたソフトウェアなので、当然オープンソースライセンスを設定しますが、それには、いろいろな種類があります。結論から先に言うと、筆者は日ごろからお世話になっている[[https://ja.wikipedia.org/wiki/MIT_License|MITライセンス]]を選択しました。GitHubに用意されているLICENSEファイルがほとんどそのまま使用でき、悩んだのは著作権者の名前くらいでした（本名にするかハンドル名のするかw）。 MITライセンスは、オープンソースライセンスの中では[[https://ja.wikipedia.org/wiki/%E3%83%91%E3%83%BC%E3%83%9F%E3%83%83%E3%82%B7%E3%83%96%E3%83%BB%E3%83%A9%E3%82%A4%E3%82%BB%E3%83%B3%E3%82%B9|パーミッシブ・ライセンス]]に分類されるライセンス形態で、同じ形態を取るライセンスとしては[[https://ja.wikipedia.org/wiki/BSD%E3%83%A9%E3%82%A4%E3%82%BB%E3%83%B3%E3%82%B9|BSD系ライセンス]]や[[https://ja.wikipedia.org/wiki/Apache_License|Apacheライセンス]]があります。たま、他の形態としては、[[https://ja.wikipedia.org/wiki/%E3%82%B3%E3%83%94%E3%83%BC%E3%83%AC%E3%83%95%E3%83%88|コピーレフト]]として有名な[[https://ja.wikipedia.org/wiki/GNU_General_Public_License|GLPライセンス]]があります。 ライセンスの選択に迷ったら、GitHubが公開している以下のサイトをご覧下さい。 * https://choosealicense.com/ \\ ===== リリースする ===== 初版のソースコードの準備が終了したら、GitHubでそのリポジトリに対してリリースを作成します。 GitHubのリポジトリ apricot の画面を表示します。 [{{:github:publish:github-publish21.png?nolink|}}] ■ 右サイドの [Releases] 下の [Create a new release] をクリックします。 [{{:github:publish:github-publish22.png?nolink|}}] ■ [Tag version]を入力します。\\ ■ [Release title]を入力します。\\ ■ [Describe this release]を入力します。\\ ■ 緑色の[Publish release]ボタンを押して下さい。 === バージョン番号について === GitHubではタグの付け方は、バージョン番号の前に ''v'' を付けるのが一般的です。例として、''v1.2'' や ''v1.2.3'' などがあります。また、バージョン番号については、[[https://semver.org/lang/ja/|セマンティック バージョニング]]に準拠することが推奨されています。GitHubのタグとリリースの作成については、本編の [[github:release|ここ]] を参照して下さい。 [{{:github:publish:github-publish23.png?nolink|}}] ■ リリースが完了すると上の画面が表示されます。 お疲れ様でした。\\ 引き続き、Packagistへの登録を行いたい方は、[[packagist:top|こちら]] をご覧下さい。 \\