貢献

こんにちは! Jekyllへの貢献に興味がありますか? あなたの助けが大好きです。Jekyllはオープンソースプロジェクトで、あなたのようなユーザーの貢献の積み重ねでできています。

問題の報告や助けを得る場所

サポートガイドラインを見てください。

貢献の仕方

あなたが開発者でも、デザイナーでも、あるいは単にJekyllの信者でも、貢献する方法はたくさんあります。ここにいくつかのアイデアを示します。

  • コンピュータにJekyllをインストールし、ざっと操作を行ってみてください。動きましたか? 希望通りの動作ですか? そうでなければ、issueを開き知らせてください。
  • プロジェクトの開いているissueにコメントしてください。同じ問題を経験しましたか? 回避策を知っていますか? この機能がどのように優れているかについての提案はありますか?
  • documentationを読み、”improve this page”をクリックしてください。何かを混乱させているのを見たり、改善することができる何かについての提案をしている時はいつでも。
  • Jekyll discussion forumをブラウズして、質問に手を貸してください。他のユーザーが体験していることを既に経験していれば、いいチャンスです。
  • 未解決のissue(特にhelp-wantedのラベル)のもの)を見つけて、修正案を提出してください。それがあなたの最初のプルリクエストであるならば、我々は噛み付かないと約束します、そして、どんな質問にでも答えて喜んでいます。
  • 変更をローカルでテストし、提案内容を確認することは、オープンプルリクエストを評価するのに役立ちます。

プルリクエストの送信

プルリクエストの基本

  • 提案された変更は小さい方が良いです。無関係な変更を2つ提案する場合は、2つのプルリクエストを送信してください。
  • 情報が多いほど、優れています。プルリクエストボディをしっかりと使用してください。どのような変更が行われたのか、なぜ変更が行われたのか、およびそれらがユーザーに与える影響について説明します。
  • これがあなたの最初のプルリクエストなら、それはGitHub Flowを理解するのを助けるかもしれません。
  • コードの投稿を送信する場合は、必ず以下のコードへの貢献セクションを読んでください。

github.comでのプルリクエストの送信

github.comのWebインターフェースを介して、多くの小さな変更を完全に行うことができます。

  1. 編集を行うjekyll/jekyll内のファイルに移動します。
  2. ファイルを編集するために、右上の鉛筆のアイコンをクリックします。
  3. 提案する変更を行います。
  4. “Propose file change”をクリックします。
  5. “Create pull request”をクリックします。
  6. 提案する変更の説明的なタイトルと詳細な説明を追加します。詳しい方が良いです。
  7. “Create pull request”をクリックします。

以上です。提案した変更を他の人が確認してフィードバックを提供すると、自動的に更新を受け取るように登録されます。

Gitコマンドラインでプルリクエストを送信する

  1. jekyll/jekyllの右上のコーナーの”Fork”をクリックし、プロジェクトをForkします。
  2. git clone https://github.com/<you-username>/jekyllでローカルリポジトリにクローンします。
  3. 変更を行うための、説明的な名前のブランチを作成します。( git checkout -b my-awesome-feature )
  4. 修正とテストを行います。必ずしも必要な手順ではありません。
  5. script/cibuildを実行して、また全てが上手くいくことを確認してください。(テストセクションもご確認ください)
  6. ブランチをプッシュします( git push origin my-awesome-feature )。
  7. https://github.com/<your-username>/jekyllに行き、プルリクエストを作成します。そして、画面上部の指示に従ってください。

ドキュメントの更新を提案する

Jekyllのドキュメンテーションをできるだけベストな状態にしたいと考えています。ドキュメンテーションをオープンソース化しており、かけているところを見つけられた際はプルリクエストを送信してください。

変更の送信の仕方

jekyllrb.comのドキュメンテーションはdocsディレクトリにあります。上のセクションを見て、変更の情報をプルリクエストで送信してください。

注意点を一つ。すべてのpullリクエストはmasterブランチ(デフォルトのブランチ)に向けてください。

jekyllrb.comのFontAwesome iconsetを更新

使用しているアイコンだけを含む、カスタムバージョンのFontAwesomeを使用しています。

カスタムアイコンセットでまだ使用できないアイコンを使用してドキュメンテーションを更新する必要がある場合、Icomoon’s Generatorを使用してアイコンをレンダリングし直す必要があります。

  1. https://icomoon.io/app/に行きます。
  2. 上部のバーのImport Iconsをクリックし、<jekyll>/docs/icomoon-selection.jsonを実行してアップロードします。
  3. ページの下のAdd Icons from Library..をクリックし、’Font Awesome’を追加します。
  4. ライブラリから必要なアイコンを選択します(’IcoMoon-Free’ライブラリの代わりに’FontAwesome’ライブラリを使用してください)。
  5. ボタンのバーのGenerate Fontをクリックします。
  6. 含まれるアイコンを確認して、Downloadをクリックして次に進みます。
  7. フォントファイルを抽出し、CSSをJekyllで使用しているパスに適応させます。
    • fontsディレクトリ全体をコピーし、<jekyll>/docs/のそれを上書きします。
    • selection.jsonの内容をコピーし、<jekyll>/docs/icomoon-selection.jsonの内容を上書きします。
    • @font-face {}の宣言をコピーし、新しいアイコンのcss宣言だけを<jekyll>/docs/_sass/_font-awesome.scssのsass部分を更新します。
    • @font-face {}宣言のパスのfonts/FontAwesome.*の前に../を追加してパスを修正します。('../fonts/Fontawesome.woff?9h6hxj')の様にします。

コードへの貢献

プルリクエストの送信に興味がありますか? あなたが落とし穴にはまるのを避けられるように、いくつかの共通の注意事項を示します。

テストとドキュメンテーション

コードの変更を提案するときはいつでも、ドキュメンテーションとテストの更新を同じプルリクエストに含めてください。

ドキュメンテーション

あなたの貢献がJekyllの振る舞いを変えるなら、ドキュメンテーションを必ず更新してください。ドキュメンテーションはdocs/_docsフォルダにあります(警報:それはJekyllサイトです!)。ドキュメントに情報が欠けている場合は、気軽に追加してください。優れたドキュメントは、プロジェクトを素晴らしいものにします。プルリクエストにドキュメントの変更を含めると、マージ時にjekyllrb.comが更新されます。

テスト

  • 既存の機能に対して小さな修正やパッチを作成する場合は、簡単なテストで十分です。通常、testsフォルダの既存の例からコピー&ペーストすることができますが、必要に応じて私たちのテストsuiteのShouldaRSpec-Mocksについて調べてください。
  • 全く新しい機能なら、新しいCucumberを作成し、必要に応じて既存の手順を再利用してください。

コード貢献の基本

  • JekyllはRubocop静的アナライザーを使って、貢献がGitHub Ruby Styleguideに従っていることを確認してます。あなたのブランチをプッシュする前に、script/fmtを使ってあなたのコードをチェックし、エラーを解決してください。
  • プルリクエストでGemバージョンをbumpしないでください(意味がわからない場合は、おそらくしなかったでしょう)。
  • script/consoleのコマンドを使ってREPLを起動し、Jekyllのメソッドの結果を調べることができます。また、サイトや設定をすばやく作成するのに役立つ方法もあります。ぜひお試しください!

ローカルでのテスト実行

依存関係をテスト

テストsuiteを実行し、Jekyllの依存関係に必要なgemを構築するために、以下のコマンドを実行します。

script/bootstrap

変更を行う前に、テストを実行しパスすることを確認します(環境が正しく設定されていることを確認します)。

script/cibuild

test/内のファイルだけを更新した場合は、次のコマンドを使います。

script/test test/blah_test.rb

.featureファイルだけを更新した場合は、次のコマンドを使用します。

script/cucumber features/blah.feature

script/testscript/cucumberはどちらも引数なしで実行することができ、その場合はそれぞれのsuite全体を実行します。

Visual Studio Code Development Container

Visual Studio CodeRemote Development Extension Packとともにインストール済みであれば、Visual Studio Codeでこのリポジトリを簡単に開き、”Re-open In A Development Container”のプロンプトに従うと、セットアップが完了し、すべての要件がインストールされた新しい環境で使用できるようになります。

A thank you

ありがとうございます。Jekyllをハッキングするのは楽しいはずです。もしあなたがこれを理解するのが難しいと思うなら、私たちが私たちのプロセスやドキュメンテーションを改善できるように知らせてください!