コンテンツにスキップ

GitLabでのホスティング

  • すべてを追加してコミットする

    $ git add -A && git commit -am "shard complete"

  • shard.ymlで指定されているのと同じnameとdescriptionでGitLabプロジェクトを作成します。

  • リモートを追加します。（<YOUR-GITLAB-USERNAME>と<YOUR-REPOSITORY-NAME>を適宜置き換えてください）

    $ git remote add origin https://gitlab.com/<YOUR-GITLAB-USERNAME>/<YOUR-REPOSITORY-NAME>.git

    SSHを使用する場合は

    $ git remote add origin git@gitlab.com:<YOUR-GITLAB-USERNAME>/<YOUR-REPOSITORY-NAME>.git

  • プッシュする

    $ git push origin master

パイプライン

次に、コードをリポジトリにプッシュしたときにテストを実行し、ドキュメントをビルド/デプロイできるGitLabパイプラインを設定しましょう。

単純に、次のファイルをリポジトリのルートに追加して、.gitlab-ci.ymlという名前を付けます。

image: "crystallang/crystal:latest"

before_script:
  - shards install

cache:
  paths:
  - lib/

spec & format:
  script:
  - crystal spec
  - crystal tool format --check

pages:
  stage: deploy
  script:
  - crystal docs -o public src/palindrome-example.cr
  artifacts:
    paths:
    - public
  only:
  - master

これは2つのジョブを作成します。最初のジョブは「spec & format」というタイトルです（好きな名前を使用できます）。デフォルトでは、パイプラインの「test」ステージに入ります。 imageで指定されたdockerコンテナの真新しいインスタンスで、scriptのコマンドの配列を実行するだけです。おそらく、そのコンテナをあなたが使用しているcrystalのバージョン（shard.ymlで指定されているもの）にロックしたいと思うでしょうが、この例では、単にlatestタグを使用します。

パイプラインのテストステージは、（配列の各要素が正常な終了コードを返した場合）合格するか、（要素の1つがエラーを返した場合）失敗します.

合格した場合、パイプラインはここで定義した2番目のジョブに進みます。これは名前を付ける必要があります "pages"。これは、gitlabページサイトにコンテンツをデプロイするための特別なジョブです！これは、「deploy」ステージで発生するように指定したため、テストに合格した後に実行されます。再びscriptのコマンドを実行しますが（今回はドキュメントをビルドします）、今回はパスpublic（ドキュメントを隠した場所）をジョブの成果物として保持するように指示します。

このジョブにpagesという名前を付け、ドキュメントをpublicディレクトリに配置し、それをartifactとして指定した結果、GitLabはそのディレクトリにあるサイトをデフォルトのURL https://<YOUR-GITLAB-USERNAME>.gitlab.io/<YOUR-REPOSITORY-NAME>にデプロイします。

ファイル内のbefore_scriptとcacheキーは、すべてのジョブで同じスクリプト（shards install）を実行し、作成されたファイル（cache）を保持するためのものです。シャードに依存関係がない場合は必要ありません.

上記のファイルをプロジェクトにコミットしてプッシュすると、新しいパイプラインの最初の実行がトリガーされます.

$ git add -A && git commit -am 'Add .gitlab-ci.yml' && git push origin master

バッジ

パイプラインの実行中に、プロジェクトにバッジを添付して、ドキュメントと（うまくいけば）パイプラインの正常な状態を示しましょう。（バッジのドキュメントを読むことをお勧めします。）

バッジは画像付きのリンクにすぎません。そのため、パイプラインへのリンクを作成し、GitlabパイプラインバッジAPIからバッジ画像を取得しましょう。

_全般_設定の_バッジ_セクションで、最初にリリースバッジを追加します。リンクは次のとおりです。https://gitlab.com/<YOUR-GITLAB-USERNAME>/<YOUR-REPOSITORY-NAME>/pipelines _バッジ画像URL_は次のとおりです。https://gitlab.com/<YOUR-GITLAB-USERNAME>/<YOUR-REPOSITORY-NAME>/badges/master/pipeline.svg.

そして、パイプラインが完了したら、ドキュメントが完成し、shields.ioの汎用バッジでそれらにリンクできます。

  • リンク：https://<YOUR-GITLAB-USERNAME>.gitlab.io/<YOUR-REPOSITORY-NAME>
  • 画像：https://img.shields.io/badge/docs-available-brightgreen.svg

リリース

リリースとは、履歴の中で名前が付けられた特別なコミットのことです（タグ付けを参照）。

Crystal ShardsのREADMEによると、

Gitリポジトリからライブラリをインストールする場合、リポジトリには、vというプレフィックスが付いた、セマンティックバージョニングのような形式に従ったバージョタグが必要です。例：v1.2.3、v2.0.0-rc1、またはv2017.04.1

GitLabには、リリース機能もあり、このタグにファイルと説明を関連付けることができます。こうすることで、（たとえば）バイナリを配布できます.

リリースドキュメントからわかるように、UIでリリースノート/ファイルとともに_アノテーション付き_タグを作成するか、

gitlab new tags UI

コマンドラインから次のようにタグを作成できます

$ git tag -a v0.1.0 -m "Release v0.1.0"

プッシュする

$ git push origin master --follow-tags

その後、UIを使用してリリースノートを追加/編集し、ファイルを添付します.

ベストプラクティス

リリースバッジ

必要に応じて、リリースにshields.ioバッジを追加することもできます。GitLabはこの種のものに完全には対応しておらず、誰かがshields.ioにgitlabのバージョンバッジを追加するまでは、URLにバージョン番号を直接コード化する必要があります.

  • リンク：https://img.shields.io/badge/release-<VERSION>-brightgreen.svg
  • 画像：https://img.shields.io/badge/release-<VERSION>-brightgreen.svg

ここで、<VERSION>はv0.1.0のようにvがプレフィックスされたバージョン番号です。

GitHubへのミラーリング

GitHubのプロジェクトは通常、より多くの露出と他のサービスとのより良い統合を備えているため、ライブラリもそこにホストしたい場合は、GitLabからGitHubへの「プッシュミラー」を設定できます。

  1. プロジェクトと同じ名前のGitHubリポジトリを作成します。
  2. ここの指示に従ってください：https://docs.gitlab.com/ee/workflow/repository_mirroring.html#setting-up-a-push-mirror-from-gitlab-to-github-core
  3. GitHubの説明を編集します。次のように使用できます
    • 説明：前後に同じ単語。これはミラーです
    • リンク：https://gitlab.com/<YOUR-GITLAB-USERNAME>/<YOUR-REPOSITORY-NAME>/

これはプッシュミラーであるため、変更は一方向にのみ伝播されます。そのため、潜在的な協力者に、プルリクエストと問題はGitLabプロジェクトに送信する必要があることを知らせてください.