はじめに
転職活動用のポートフォリオを作るにあたりインデックス的なHPを作成することにしました。
なお、筆者は文系出身。SIerにてJava、PHPの業務経験がありますがプライベートでのアウトプットは行ったことがないです。
なお、どこでどう躓いたかどう対策したかを記録する目的もあり、手戻りである部分を残しております。
手戻りがない形で最初からきれいに作れる手順は「参考」に書かれているサイトなどで確認できますので、特別な理由がなければそちらを参照されることをお勧めします。
また、ここではVue、Git、GitHub、GitHubPages、VisualStudioCodeを使った「開発環境の構築」や「開発方針・開発手法の確立」までをまとめております。
具体的なHP作成の過程は別にまとめようと思います。
HP作成に当たる過程
READMEの検討
最初はHP作成は考えておらず、GitHubのREADME.mdをきれいに整えてポートフォリオへの導線を作ろうと思いましたが、いきなりGitHubのリポジトリが見えるのが文系にはどうも受け付けなく方向チェンジ。
markdown方式である程度整えられることだけ確認した…。
Pages
GitHub PagesというホスティングサービスがHP作成の要件にマッチしていたのでこちらを使って作成することに。
- 静的サイト (HTML や CSS, 画像など) を公開できる。JavaScript も動作。
- 独自ドメインを割り当てることも可能です。(https://ユーザまたは組織名.github.io/リポジトリ名)
- 無料。 ※ポートフォリオ(まだない)は動的なRubyやGoを作成予定なので別途サーバーとドメインを取得する必要があるが、インデックスHPならここで十分。
最終目標
目標は以下とした。インデックスページを作るだけならべた書きでできるのだけれどせっかくならここでも何かしたい。
- Java、PHP、HTML、CSS、javascriptの基礎はすでにあるため新しい技術を使って作成する。
- ついでにこのHPもポートフォリオの一部にする。
- ポートフォリオ(まだない)へのリンクを貼る機能。
- 作成したものをGit管理し、GitHubで参照できるようにする。
- その他、上記の事をQiitaに書き、技術の勉強方法の確立、アウトプットの癖付けを行う。
技術選定
ポートフォリオは別に作る予定なので、ここにあまり時間をかけられないこともあり学習コストの低いVue.jsを選択。
他候補は、Reactでした。
Vue.jsを学習
Vue.js とは?
こちらを一通り読みました。
いよいよ使ってみる
ここでは、Vueでの開発ができることとGitHubへのアップロード手順を確立する。
インストール
<script src="https://cdn.jsdelivr.net/npm/vue"></script>
このように直接jsに1行書くだけでVue.jsは使えるがついでにこのHPもポートフォリオの一部にするを考慮すると冗長になる構成は避けたかったのと、いくつかの使えない機能(Jestなど)ものちに使いたかったためCLIを利用。
yarnを入れる
$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
$ brew install yarn
Vue CLI をグローバル環境にインストールする
$ yarn global add @vue/cli
$ yarn global add @vue/cli-init
プロジェクト作成
$ vue init webpack homepage-project
? Project name homepage-project
? Project description A Vue.js project
? Author yuko
? Vue build standalone
? Install vue-router? Yes
? Use ESLint to lint your code? Yes
? Pick an ESLint preset Standard
? Set up unit tests Yes
? Pick a test runner jest
? Setup e2e tests with Nightwatch? Yes
? Should we run `npm install` for you after the project has been created? (recom
mended) npm
webpackはテンプレート。諸々の質問に答えてセットアップを待つ。
# Project initialization finished!
# ========================
To get started:
cd homepage-project
npm run dev
Documentation can be found at https://vuejs-templates.github.io/webpack
$ cd homepage-project
$ npm run dev
DONE Compiled successfully in 3150ms
I Your application is running here: http://localhost:8080
開発用モードでサーバが稼働したのでブラウザに「http://localhost:8080」を打って画面が表示されることを確認
終了するときは、Control+C
フォルダ構成の把握
PROJECT_ROOT
┣ build
┣ config
┣ node_modules
┣ src
┣ assets #画像やCSS、その他javascriptなどの静的ファイルが含まれる
┣ components #.vueの拡張子がついたコンポーネントファイルが含まれる
┣ router #ルーティング用の設定ファイルが含まれる
┣ App.vue #index.htmlに出力されるvue側のインデックスファイル
┗ main.js #各種ファイルをインポートして管理するエントリーポイント用ファイル
┣ static
┣ test
┗ index.html #ルートファイル
index.js、src/配下を触る必要があることを把握
参考:vue-cliの導入から新規でVue.jsのプロジェクト作成とビルド方法まとめ
参考:vue-cliで始めるVue.jsチュートリアル (1)
ビルドにより生成されるパッケージ
さらに構成把握のためビルドを行い、初期状態では存在していないdistを作成します。
$ npm run build
PROJECT_ROOT
┣ dist
┣ static
┣ index.html
設計
フォルダ構成の把握にて確認した内容を元に開発方針を整理。とりあえず以下の方針で動作確認を行います。
用意されたテンプレートをどう使っていくか
/src/router/index.js
まずは、作成するHPのコンテンツへのルーティングの設定。
/
へアクセスしたときのルーティング先をHelloWorldから変更もしくはサブディレクトリのルーティングを追加することが考えられるが、ざっと探した限りHelloWorldは残している方が多いので、一旦サブディレクトリ作成の方針にする。
また、HPコンテンツのコンポーネントファイルをインポートする。/src/components/
HPコンテンツのコンポーネントファイルを追加。/src/assets/
HPコンテンツの画像などを格納する。(((今は何も考えられない)))
ファイル管理
次は、ファイル管理です。筆者はsvn(TortoiseSVN)での業務経験があります。
大好きなツールなのですが、今回はGitを使います。
参考:いちばんやさしいGit&GitHubの教本 人気講師が教えるバージョン管理&共有入門
参考:Visual Studio CodeでGitを使う
設定
まずはGitの確認をしたところすでに入っている模様(macはデフォルトで入っている模様)
$ git --version
git version 2.20.1 (Apple Git-117)
コミット時に記録されるアカウント情報の設定を行います。
$ git config --global user.name XXXXXX
$ git config --global user.email XXXX@XXXX
ファイル管理の方向性
動作確認しながらの更新が想定されるので、masterに直接コミットするのではなく
別のブランチを作成しそちらにコミットして確認、問題なければmasterにマージという形をとることにします。
Repositorie
┣ masterブランチ //公開用
┣ gh-pagesブランチ //作業用細かい修正はこちらで行っていく
gh-pagesなのは、後述しますがGitHub Pagesを使えるブランチ名がmasterかgh-pagesのため。
開発中は、gh-pagesをGitHub Pagesとして設定して動作確認、
ひと段落したら、masterへのマージを行いGitHub Pagesの設定をmasterに変更をイメージしています。
なお、初回はmasterにコミットしそこからブランチを分けて開発という進め方ですので初回コミットはmasterに対して行います。
ローカルリポジトリを作成
方向性が決まったところで、先ほどつくったプロジェクトをファイル管理できるようにしていきます。
1.ディレクトリの作成
先ほどのプロジェクトをディレクトリとするのでここでは何もしません。
2.Gitリポジトリに変換
$ cd homepage-project //ファイル管理したいプロジェクトのルートに移動
$ git init //Gitリポジトリに変換
$ git status //Gitのステータス確認
On branch master
No commits yet
Untracked files:
(use "git add <file>..." to include in what will be committed)
.babelrc
.editorconfig
.eslintignore
.eslintrc.js
.gitignore
.postcssrc.js
README.md
build/
config/
index.html
package-lock.json
package.json
src/
static/
test/
nothing added to commit but untracked files present (use "git add" to track)
ここでいくつかのファイルやディレクトリがないことに気づく。
自動的に管理対象としない除外ファイルを判断してくれているようです。
ログファイルや生成物(ここではdist配下)はファイル管理しない方がいいよねということでしょう。
$ cat .gitignore
.DS_Store
node_modules/
/dist/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
/test/unit/coverage/
/test/e2e/reports/
selenium-debug.log
# Editor directories and files
.idea
.vscode
*.suo
*.ntvs*
*.njsproj
*.sln
distはパッケージファイルなので確かにファイル管理すべきではないと思われます。
ただ今回はGitHub Pagesが公開先ということもあり、そのままコミットできるようにします。
$ vi .gitignore
----------------
#/dist/
出てくるようになりました。
$ git status
On branch master
No commits yet
Untracked files:
(use "git add <file>..." to include in what will be committed)
.babelrc
.editorconfig
.eslintignore
.eslintrc.js
.gitignore
.postcssrc.js
README.md
build/
config/
dist/
index.html
package-lock.json
package.json
src/
static/
test/
nothing added to commit but untracked files present (use "git add" to track)
コミット
$ git add . //ステージングエリアに登録
$ git commit -m "first commit" //コミットとメッセージ
リモートリポジトリの作成
GitHubにうつり、「New Repository」を押下し、必要な情報を入力したリポジトリを作成
作成したリポジトリを開くと何をすればいいか状況に合わせて書いてある。今回は下のパターンなのでそのままコマンドを実行
$ git remote add origin git@github.com:c3drive/homepage-project.git
$ git push -u origin master
git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.
GitHubに公開鍵がなくてエラーになりましたので、PCの公開鍵をGitHubに登録します。
公開鍵の設定
パソコンのSSH Keyを生成します。
$ ssh-keygen -t rsa -b 4096 -C "XXXXX@XXXXX"
Generating public/private rsa key pair.
Enter file in which to save the key (/Users/XXXXX/.ssh/id_rsa): //鍵の保管場所を確認しEnter
Enter passphrase (empty for no passphrase): //パスフレーズを入力してEnter
Enter same passphrase again: //再度パスフレーズを入力してEnter
作成された公開鍵をコピー
$ pbcopy < /Users/XXXXX/.ssh/id_rsa.pub
GitHubのSettings>SSH and GPG keysにて「New SSH key」を押下しコピーしたキー内容を入力する。
再度コマンドを実行し、パスフレーズを入れる
$ git remote add origin git@github.com:c3drive/homepage-project.git
$ git push -u origin master
Enter passphrase for key '/Users/XXXXX/.ssh/id_rsa':
無事GitHub上のリモートリポジトリに表示されるようになりました…!
警告が出ているので確認します。
それぞれバージョンを上げろと言われていました。
webpackはプロジェクトを作る時に指定しているテンプレート。
よく見ると以下のような記述がありました。
webpack-bundle-analyzer vulnerability found in package.json 26 minutes ago
package.jsonを確認すると依存関係で上記の記述があるのでGitHubの指定通りに直せばよさそうです。
以後のファイル変更は当初の予定通りmasterとは別のブランチをきって行う予定のためいったん放置します。
- package.jsonのUpgrade webpack-bundle-analyzer to version 3.3.2 or later.対応
- package.jsonのUpgrade webpack-dev-server to version 3.1.11 or later. 対応
GitHubPagesの設定の確認
動作確認のため、Repository>SettingsからGitHub Pagesの設定を確認します。
以下の公開ができるようです。
- masterブランチ
- masterブランチ/docs
- gh-pagesブランチ ※現在表示されておらずこの名前のブランチを作成したときに限り表示
参考:https://help.github.com/en/articles/configuring-a-publishing-source-for-github-pages
masterはVueプロジェクトのソースとdistという構成ですが、静的なHTMLとして公開できるのはdistのみですのでmaster全体を公開する必要はなさそうです。
GitHubPagesにとってはdocsが公開ディレクトリ扱いの様ですので、以下の修正を後で行うことにします。
- package.jsonのUpgrade webpack-bundle-analyzer to version 3.3.2 or later.対応
- package.jsonのUpgrade webpack-dev-server to version 3.1.11 or later. 対応
- 開発用のブランチはgh-pagesとする
- Vueから生成されるパッケージをdistからdocsへ変更
- すでに作られているdistを削除する
- .gitignoreでコメントアウトしたdistのイン(存在しないディレクトリになるので行ごと削除がいいかもしれません)
現時点で、master/docsはないのでいったんmasterを公開する設定にして動作確認。
真っ白です。コンソールよりindex.htmlで読み込んでいるファイルのパスが「/」ルート指定です。
しかしこれらのファイルは、「/homepage-project/dist/」配下にあります。
こちらは相対パスにするように修正します。
- package.jsonのUpgrade webpack-bundle-analyzer to version 3.3.2 or later.対応
- package.jsonのUpgrade webpack-dev-server to version 3.1.11 or later. 対応
- 開発用のブランチはgh-pagesとする
- Vueから生成されるパッケージをdistからdocsへ変更
- すでに作られているdistを削除する
- .gitignoreでコメントアウトしたdistのイン(存在しないディレクトリになるので行ごと削除がいいかもしれません)
- パッケージの参照ファイルを相対パスに変更
課題の管理
GitHub Pagesの表示の確認ができませんでしたが、ワンパス通してみて色々と問題点がわかりました。
これから開発用のブランチを切り、TODOの消化(問題の修正)とHP作成を行っていくのですが、GitHubにIssuesというタブがあるのでTODOをこちで管理してみようと思います。
参考:チーム開発を変える「GitHub」とは?〜Issuesの使い方〜【連載第3回】
必要事項を入力します。対応するのは自分しかいないので自分を選択し、ラベルはデフォルトを使いました。
すべてのTODOをIssuesに移せました。
プロジェクトの管理
ここで課題の進捗状況やタスクの消化状況を把握するのにProjectを作った方がいいことに気づく。
参考:新入社員におくるGitHubでのプロジェクト管理の初歩
詳細割愛しますが、Projectのタスク管理を試したかったのでHPとしてProjectを作成。
よく見かけるのは「TODO」「DoingやDeveloping」「Reviewing」「Done」の4種類ですが、
GitHubが用意したPresetは「To do」「In progress」「Done」の3種類であり、
「In progress」を「Doing」と「Reviewing」でMoveの設定を分けるイメージが湧かなかったので
3種類で運用することにしました。(手動でのタスク移動前提、状況の可視化という意味で「Doing」は現場では必須かと思いますが、自分はMoveの設定を試したかったので混乱するカラムはやめるという判断です)
設定はそれぞれ以下の通り。
TODOカラム:未着手のタスク(まだない)やIssueはここ。
Newly addedは、Issueが登録されたとき、自動的にこのカラムに追加設置されるように設定
※今回は先にIssueを作ってしまったので手で登録しました。以後Issue作成時にProjectを紐づけてつくると自動でここに来るようになる
開発用ブランチの作成
ブランチを作成します。
$ git branch gh-pages //ブランチの作成
$ git branch //ブランチの状態の確認
gh-pages //gh-pagesが作成されているが
* master //まだ使用しているのはmaster
チェックアウトにて使用ブランチの変更
$ git checkout gh-pages //ブランチ切り替え
Switched to branch 'gh-pages'
$ git branch
* gh-pages //切り替わったことを確認
master
この時点ではローカルリポジトリでの作業のみのためGitHubで確認はできません。
作成したブランチをリモートリポジトリに反映します。
$ git push -u origin gh-pages
GitHubで作成したブランチが認識されたので、ついでにGitHubPagesも変更しておきます。
開発ツールの導入
ここで、コマンドラインでの環境構築ではこれ以上進めるのが厳しいと判断し、VSCodeでの環境を構築する。
なお、コマンドラインのみで開発すると以下のような手順となる。
1.ファイル編集
$ vi xxx
2.ビルド
$ npm run dev
WARNING Compiled with 1 warnings
✘ http://eslint.org/docs/rules/key-spacing Missing space before value for key 'component'
src/router/index.js:19:17
component:Portfolio
^
✘ 1 problem (1 error, 0 warnings)
Errors:
3.http://localhost:8080で動作確認
4.修正がある場合、Controll+C
で終了し、1へ
Visual Studio Codeのインストール
参考:Visual Studio CodeでVue.jsアプリケーションの開発環境を構築する
1.microsoft.com - Visual Studio Codeより、インストール。
2.左ペインからinstallを押下して、必要な拡張機能を適用する。
- Japanese Language Pack for Visual Studio Code 日本語化
- Vetur Vueファイルのためのツール
- ESLint JavaScript のための静的検証ツール
1.VSCodeにて、ファイル編集
2.ビルド(これはVSCodeのターミナル上でも今まで開いていたターミナルでもどちらでも)
3.http://localhost:8080で動作確認
4.修正がある場合、1へ(2、3はこのままリアルタイムで反映されるようになる)
開発
ブランチでの動作確認
Webサイトの開発の前にIssueを解消してBranchでのWebサイト表示ができるようにします。
まずはSecurity Alartsの対応
- webpack-bundle-analyzerが古い #1
"webpack-bundle-analyzer": "^2.0.1", // 変更前
"webpack-bundle-analyzer": "^3.4.1", // 変更後
==============================================
【追記】
メジャーバージョンアップとなっているため、影響はきちんと確認する必要があります。
特にwebpackはメジャーバージョンアップにおいて関連するwebpackのバージョンなども合わせないときちんと動作しないことが多く、
設定ファイルの定義の仕方から変わっていることも多いため普通に移行に苦労する代物なのでこのようにフランクにアップすべきものではないです。
また、当たり前ですがpakage.jsonを直接編集した場合、npmコマンドにてアップデートを行ってください。
(package.jsonはあくまでパッケージ管理ファイルでありnpmコマンドを使うことで初めてインストールなりアップデートが行われます)
この当たり前の知識すらなかった私は、package.jsonを直接変更したまま、npmの処理をせず、別のパッケージをインストールして依存関係を解消した時に、このメジャーバージョンアップがひっそり実施されてしまい、問題の切り分けに苦労しました。
参考:vue+webpack環境にて、npm run devのエラーがどうしようもなくなった件
===============================================
変更をコミットしリモートリポジトリにpush
ここで、コメントに対応するIssueの番号をつけると紐づけてくれる。
$ git add package.json
$ git commit -m "Security Alerts Measure #1"
[gh-pages 67e37d4] Security Alerts Measure #1
1 file changed, 1 insertion(+), 1 deletion(-)
$ git push
- webpack-dev-serverが古い #2
こちらも同じように対応を行う。 同時にコミットをしなかったのはIssueの単位でコミットしたかったため。(pushは一緒でもよかった…。)
GitHubで確認するとIssueにコミットが紐づいていることがわかる
Securityの警告、masterも対応しないと消えないようなので、一旦#1,2の対応のみでプルリクエストを出します。
一人で開発しているためレビュアーは指定できなかったのでタイトル、説明、アサイン、Project、マイルストーンなどセットし「Create pull request」を押下
Projectを見ると、紐づけたマイルストーンがReviewingカラムに自動で移動していました。
(Issueはダメなのか…)
作成されたPull Requestのレビュー承認をしようとしたら本人はできない模様。
仕方ないのでそのまま「Merge pull request」を押下してマージ。
リモートリポジトリで行なった作業(マージ)をローカルに反映させます。
$ git checkout master //ブランチの切り替え
$ git branch //masterに切り替わっていることを確認
gh-pages
* master
$ git pull origin master //リモートリポジトリから変更を反映
失敗1/2
Pull requestと同時にIssueをCloseさせるべきだった
Projectを確認すると、マイルストーンは移動しましたが、Issueは手動でCloseが必要な様子。
IssueタブにてそれぞれCloseしたら無事Doneへ移動しました。
こちら、マージする時のコメントに「[close #1 #2]」としてたらおそらくマージと同時にIssueがクローズされ、CloseがMove条件となっているDoneカラムへの移動も同時に行われたのかなと思います。
参考:Closing issues using keywords
失敗2/2
マージ時に開発用ブランチのコミット履歴まで残してしまった
masterへのコミットを必要最低限にする為に開発用ブランチを作っているのに全コミットが載ってしまう状態。
これは、マージ時にデフォルトで履歴を残す方法が選択されているのをそのまま使ってしまったのが原因でした。
- Create a merge commit:マージ元のコミット履歴、マージそのものの履歴が残る
- Rebase and merge:マージ元のコミット履歴だけ残る
- Squash and merge:マージ履歴が残る
参考:GithubでのWeb上からのマージの仕方3種とその使いどころ
やりたいことを叶えるだけなら「Squash and merge」を選べば良さそうなのですが、
現時点では以下のレビュアーがソースをレビューする単位はある程度細かい単位が望ましい認識です。
特に「Squash and merge」にした場合、もっと多くの開発者がいてブランチも複数あるような状態だと特定のコミットだけ競合など発生した時や特定のコミットを選択するなども不可に見えます。
しかしmasterは綺麗にしたく、開発用ブランチは1日の終わりなどの動作しない状態でのコミットも含まれます。
まとめると以下の状態です。
- 開発用ブランチ
コミットはなんでもない単位でも行いたい - masterブランチ
コミットはリリースの単位など大きい単位を想定
今回は一人開発なので問題ないですが、現場で使う際、レビューが現実的な単位になりません。
そこで以下のようにブランチ構成を変えることにします。
- 開発者作業用ブランチ
コミットはなんでもない単位でも行いたい
ある程度のまとまりで、Create a merge commitにて、リリース用ブランチへマージ - リリース用ブランチ
Issueの単位などある程度のまとまりをコミット
リリースできる状態になったら、Squash and mergeにて、master用ブランチへマージ - masterブランチ
コミットはリリースの単位など大きい単位を想定
※複数のリリースが並行することも考えるとやはりmasterでの競合の可能性があるので、「Squash and merge」はあまり使わない方がいいかもしれません。
ファイル管理の方向性(変更)
発覚した問題により変更します。
Repositorie
┣ masterブランチ //公開用
┣ gh-pagesブランチ //作業用細かい修正はこちらで行っていく
Repositorie
┣ masterブランチ //公開用
┣ gh-pagesブランチ //リリース用
┣ devブランチ //作業用細かい修正はこちらで行っていく
これに伴い、devブランチをgh-pagesからの派生として作成します。
$ git branch dev gh-pages //ブランチの作成(第三引数には派生元を指定)
$ git checkout dev //ブランチの切り替え
$ git branch
* dev
gh-pages
master
$ git push -u origin dev //devブランチをリモートリポジトリに反映
Issueの対応に戻る
Security Alarts以外の対応を「devブランチ」を使って行なっていきます。
以下を繰り返し、Issueを消化していく
1.ローカルリポジトリの「dev」を修正(場合により再ビルド)
2.コミット・push
3.リモートリポジトリに対してIssueの単位でdev -> gh-pagesへプルリクエスト
Projectの状況はこうなりました。
これまで発覚した問題点が解消し、TODOが0件になったのでHP作成用のIssueを新たに作りました。
HPを作っていく
作る前にざっくりマイルストーンを作りました。
紐づけているIssueはこんな感じ。
これより、このIssueをつぶしていく形でHPを作成していきますが、
開発方針や開発手法は一旦まとまったため、HP作成については別の記事にまとめようと思います。
お疲れさまでした
自分の今までの勉強法は、本を買ってきてその通りに作ってしまって実務で応用が利かないところがあったのでこういう勉強の仕方は面白かったです。
自分は先を見て計画を立てるため着手前にかなり調査を行います。
調査に当たり、先駆者様たちの記事で、手戻りがない形で先んじて言及してくださっているものが多く、
その対応をしなかった場合後ほど手戻りが出ることがある程度想定されましたが、
自身が公式ドキュメントやソースから読み解いた対応ではないものを人様の記事を見てコピペしている現状を打破したく、
手戻りがあることを想定したままあえて躓きなぜその対応が必要なのかかみ砕きながら進めました。
いつかは公式ドキュメントやソース解読により、先駆者のいない技術の先読みをある程度できるようになることが目標ですが、まだ先の様です。
つづき
HPを作成していきますが、こちらは別の記事にまとめました。
Vue.jsでHPを作成してみる - GitHub Pagesにポートフォリオサイトを作る