目次

GitHub ソースコードの公開

— y2sunlight 2020-07-03

GitHub に戻る

本章では、GitHubによってオープンソースを公開するまでを筆者の体験を基に掲載します。

オープンソースとして公開するアプリケーションは、本編でその製作過程の説明をしたApricotです。Apricotは「ちょっとしたアプリ」を作成する為の非パッケージ型のミニ・フレームワークです（本編では、これを「ステイプルワーク」と呼んでいます）。Apricotは通常のフレームワークのようにパッケージの形態を取っていないのでコア・コードを直接自由にカスタマイズして使用できます。

本章の内容は、GitHubのアカウントの取得と以下のクライアント環境を前提条件としています。GitクライアントにはEclipse( EGitプラグイン )を使用します。

クライアント環境

関連記事

リンク

GitHub

概要

本章で公開するプロジェクトの概要を示します。

プロジェクト(Eclipse)

プロジェクト名apricot
ラインセンスMIT LICENSE
ワークスペースD:\usr\github\y2sunlight

リモートリポジトリ(GitHub)

リポジトリ名apricot
リポジトリURLhttps://github.com/y2sunlight/apricot.git

ブランチ

ソースファイル構成

公開までの手順


リポジトリを準備する

新しく、公開用のリポジトリ apricot を作成し、初版のリリースの準備を行います。

リポジトリの作成

画面右上の[+]メニューから[New repository]を選択して下さい。

■ 必要な項目を入力します。

■ [Create]ボタンを押して下さい。


リポジトリについての設定

リポジトリ apricot の画面を表示します。

■ [About]右横の歯車アイコンをクリックして下さい。

■ [Description], [Website], [Topics]を編集します。
■ [Include in the home page]で必要なものにチェックを入れます。
■ [Save changes]ボタンを押して下さい。


ブランチの作成

リポジトリ apricot の画面を表示します。

■ ファイルリスト上部のドロップダウン[branch：master] をクリックします。
■ テキストボックスに 新しいブランチのブランチ名 readme-edits を入力します。
■ [Branches]内の[Create branch: readme-edits from 'master']を選択して下さい。


コラボレータの招待

プロジェクトに参加してもらえる開発者をコラボレータとして招待します。詳細は「コラボレータの招待」を参照して下さい。

リポジトリ画面の[Settings]タブを選択した後、左サイドバーで[Manage access]を選択します。

■ 右の緑色の[Invite a collaborator]ボタンを押します。

■ 招待するコラボレータのユーザ名を入力します(フルネームやメールアドレスでも可)。
■ 検索結果が表示されるので、目的の人を選択します。
■ [Add {ユーザ名} to {リポジトリ名}]ボタンを押して下さい。


Eclipse ワークスペースの準備

ワークスペースの作成

本編では、ワークスペースを以下に作成します。 

D:\\usr\github\y2sunlight


Apacheの設定

httpd.confの末尾に以下の内容を追加します。

{XAMPP Install Folder}\apache\conf\y2sunlight.conf 

# My project settings
Include conf/my-extra/*.conf

新しく、以下のフォルダを作成し、 

{XAMPP Install Folder}\apache\conf\my-extra

その中に以下の内容で、ファイル(y2sunlight.conf)を作成します。

y2sunlight.conf
Alias /y2sunlight "D:/usr/github/y2sunlight"
<Directory "D:/usr/github/y2sunlight">
  Options All
  AllowOverride All
  Require all granted
</Directory>

Apacheを再起動します。


ワークスペースの設定

Eclipseを起動しワークスペース(D:\usr\github\y2sunlight)を開きます。 Eclipseの初期設定方法については、本編「Eclipse 2019-12のインストール」のワークスペースの設定を参照して下さい。


Eclipse プロジェクトの作成

Eclipse プロジェクトのインポート

GitHubのリモートリポジトリ( apricot ) の master ブランチをインポートして Eclipseで編集できるようにします。操作方法については概略のみ説明します。詳細は、本編の「GitHub Eclipseによるリポジトリの基本操作」を参照して下さい。

以下をプロジェクトフォルダに指定します。 

D:\\usr\github\y2sunlight\apricot

Eclipseを起動して、次の手順で作業を進めます。

■ [URI]を入力します。
ここでは https://github.com/y2sunlight/apricot.git を入力します。
■ URIを入力するとそれに応じて他の項目は自動で表示されます。
■ 認証情報は必要に応じて入力して下さい。
■ [次へ]を押します。

■ ブランチ master と readme-edits の両方にチェックを入れます。
■ [次へ]を押します。

■ ローカルリポジトリの保存先にはワークスペース下のプロジェクトフォルダを指定します。
ここでは D:\usr\github\y2sunlight\apricot を指定します。
■ 初期ブランチに master を選択します。
■ [次へ]を押します。

■ [新規プロジェクト・ウイザードを使用してインポート]を選択して、[完了]を押します。

■ [PHPプロジェクト]を選択して、[次へ]を押します。
■ PHPプロジェクトの作成画面で [プロジェクト名]に apricot を入力して、[完了]を押します。

GitHubのメールとユーザ名の設定

GitHubからプロジェクトをインポートした後、まず最初にしなければならない事は、コミットメールアドレスの変更です。GitHub用のメールアドレスを設定しないとユーザ共通のメールアドレスが使用されます。ユーザ名の変更は必要に応じて行って下さい。

Eclipse で apricot リポジトリの設定画面を開きます：

  1. メニューの[ウインドウ][設定]を選択
  2. 左ペインで[チーム][Git][構成]を選択
  3. 右ペインの[構成]から[リポジトリ設定]を選択
  4. [リポジトリ]で[apricot]を選択

■ [エントリー追加…]ボタンを押します。
■ 以下の項目を必要に応じて追加して下さい。

  1. ユーザ名（キー： user.name）
  2. メールアドレス（キー： user.email）

■ [適用]ボタンを押します。


その他のEclipseの設定

ApricotではComposerを使用するので、プロジェクトにComposerのファセットを追加しておきます。

  1. プロジェクトを右クリック[プロパティー]をクリックします。
  2. [プロジェクト・ファセット][Composer]にチェックを入れ、[適用して閉じる]をクリックします。

その他は、以下を参照して設定を行って下さい。


ソースコードの準備をする

GitHubに公開する初版となるソースコードを準備します。メインとなるソースコードは、本編の「Apricot」で掲載したソースコード一式です。ここでは、そのソースコードを先に作成したプロジェクトに配置し、外部ライブラリーを再取得して、公開用のcomposer.json を作成します。

プロジェクトフォルダGitHubへの公開で不要な（環境依存している）プロジェクト関連のファイルと、実行時に作成されるフォルダやファイルを無視ファイルとして.gitignoreファイルに登録します。また、環境設定ファイルのサンプル( .env.sample )を 公開用に作成します。

ソースコードの準備ができたら、準備したこれらのファイルをリポートブランチ(master)にプッシュします。


ソースコードの配置

Apricotフォルダの内、以下に示したのフォルダまたはファイルをプロジェクトフォルダに配置します。 

apricot [プロジェクトルート]
 |
 ├── app/    ・・・ アプリケーション
 ├── assets/ ・・・ リソースファイル
 ├── config/ ・・・ 設定ファイル
 ├── core/   ・・・ コア
 ├── public/ ・・・ 公開フォルダ
 ├── var/    ・・・ データフォルダ
 └── .env    ・・・ 環境設定ファイル

全てのフォルダの構成は本編「Apricot プロジェクトの作成」のフォルダ構成フォルダ構成 を参照して下さい。


Composer.jsonの作成

まず、プロジェクトフォルダ直下で、コマンド composer init を実行して composer.json を初期化します。コマンドの途中で、以下のように質問に答えます。但し、require と require-dev の項目は後で手動で追加します。

Package namey2sunlight/apricot
DescriptionApricot is a PHP mini-framework (non-packaged version) for quickly creating simple applications.
AuthorYoshihiro Iwata <github@y2sunlight.com>
Package Typeproject
LicenseMIT

コマンドが終わると、プロジェクトフォルダ内に composer.json を作成されます。

次に、自動再生された composer.json に、require と autoload などの項目を必要に応じて追加します。

apricot/

composer.json
{
    "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"
        ]
    }
}


外部ライブラリーの設置

Apricotでは以下の外部ライブラリーを使用しています。

機能パッケージ名VsersionLevelLicense
環境変数phpdotenv5.0CoreBSD 3-Clause
ログ出力monolog2.1CoreMIT
リクエストルーターFastRoute1.3CoreSimilar to BSD 3-Clause
DIコンテナーLeague/Container3.3CoreMIT
テンプレートエンジンBladeOne3.46CoreMIT
エラーハンドラーWhoops2.7CoreMIT
デバッグ出力php-debugbar1.16CoreMIT
アセット管理assetic1.4CoreMIT
ORマッパーidiorm1.5AppBSD
バリデーターValitron1.4AppBSD 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 は以下のように書き換わります。

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 だけです。他は、後で説明する、.gitignore ファイルに指定して、リモートリリポジトリにプッシュしないようにします。


.gitignoreファイルの作成

プロジェクトフォルダ直下に以下の .gitignore を設置します。

apricot/ 

/.settings/
/.buildpath
/.project
/composer.lock
/vendor/
/.env

Apricotの以下のデータフォルダに.gitignore を設置します。

  • apricot/public/var/
  • apricot/var/cache/
  • apricot/var/db/
  • apricot/var/logs/
*
!.gitignore


環境設定ファイルのサンプル作成

公開用の環境設定ファイルのサンプル( .env.sample )を、プトジェクトフォルダ直下に作成します。

apricot/

.env.sample
# 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)にコミットします。

■ 無視ファイル以外の全てのファイルをステージして、[コミット]します。

コミットが終了したらプロジェクト・エクスプローラで、apricotを選択して[チーム][アップストリームへプッシュ]します。

GitHubのリポジトリ apricot の画面を表示します。

■ プッシュしたソースコードを確認します。


リリースの準備をする

ここでの作業は次の３つです。

Apricot本体のリファクタリング作業は、最初に本番リリースするまでは master ブランチで行い、REAMME.mdファイルとLICENSEファイルの編集作業は、別のreadme-editsブランチで行います。


ソースコード

GitHubでソースコードを公開するに当たって、以下のリファクタリングを行いました。リファクタリングの中心は名前空間の変更と英語化になります。「日本語のままでもいいかな…」と思いつつも、機械翻訳に頼って英語化しました。

また、外部ライブラリーが使用しているアセット(CSSとJs)の取り込みを手動でなく自動で出来るように、アセット管理フレームワーク Assetic を追加しました。その他、細かい点も修正しています。

GitHub公開しているApricot(V1.0)と本編で掲載しているApricot(0.9)は、異なったバージョンです。


README.mdファイル

公開するソースコードのドキュメントは必須です。使い方の分からないソースコードは意味がありません。REAMME.mdの書き方は様々ですが、最低限必要なものは、概要、インストール方法とライセンスだと思います。Apricotでは、これらに加えて、クイックスタートを書き足し、詳しい使用方法はREAMME以外で(GitHubのWiki または 当サイト)で公開する事にしました。


LICENSEファイル

GitHubでは、リポジトリ作成時にLICENSEファイルの雛形が準備されているので、ライセンスの作成がとても簡単にできます。ライセンスを明記しなかった場合は、No Licenseという扱いになり、利用者には複製、再頒布、改変が認められません。

Apricotは、公開を目的としたソフトウェアなので、当然オープンソースライセンスを設定しますが、それには、いろいろな種類があります。結論から先に言うと、筆者は日ごろからお世話になっているMITライセンスを選択しました。GitHubに用意されているLICENSEファイルがほとんどそのまま使用でき、悩んだのは著作権者の名前くらいでした（本名にするかハンドル名のするかw）。

MITライセンスは、オープンソースライセンスの中ではパーミッシブ・ライセンスに分類されるライセンス形態で、同じ形態を取るライセンスとしてはBSD系ライセンスやApacheライセンスがあります。たま、他の形態としては、コピーレフトとして有名なGLPライセンスがあります。

ライセンスの選択に迷ったら、GitHubが公開している以下のサイトをご覧下さい。


リリースする

初版のソースコードの準備が終了したら、GitHubでそのリポジトリに対してリリースを作成します。

GitHubのリポジトリ apricot の画面を表示します。

■ 右サイドの [Releases] 下の [Create a new release] をクリックします。

■ [Tag version]を入力します。
■ [Release title]を入力します。
■ [Describe this release]を入力します。
■ 緑色の[Publish release]ボタンを押して下さい。

バージョン番号について

GitHubではタグの付け方は、バージョン番号の前に v を付けるのが一般的です。例として、v1.2 や v1.2.3 などがあります。また、バージョン番号については、セマンティック バージョニングに準拠することが推奨されています。GitHubのタグとリリースの作成については、本編の ここ を参照して下さい。

■ リリースが完了すると上の画面が表示されます。

お疲れ様でした。
引き続き、Packagistへの登録を行いたい方は、こちら をご覧下さい。