GitLab をすぐに使い始められるよう、推奨される次のステップを以下に示します。
すでに慣れている方なら、この README.md を編集して自分用にカスタマイズするだけです。簡単にしたいですか?ページ下部のテンプレートを使用してください!
cd existing_repo
git remote add origin https://gitlab.com/valtersit/ruby-cve-scanner.git
git branch -M main
git push -uf origin main
GitLab の組み込み継続的インテグレーションを使用します。
この README を自分用にカスタマイズする準備ができたら、このファイルを編集し、以下の便利なテンプレートを使用してください (または、自由に好きなように構成しても構いません。これはあくまで出発点です!)。このテンプレートを提供してくれた makeareadme.com に感謝します。
プロジェクトはそれぞれ異なるため、これらのセクションのうちどれが自分のプロジェクトに当てはまるかを検討してください。テンプレートで使用されているセクションは、ほとんどのオープンソースプロジェクト向けの提案です。また、README は長すぎて詳細すぎることもありますが、短すぎるよりも長い方が良いということを覚えておいてください。README が長すぎると思う場合は、情報を削るのではなく、別の形式のドキュメントを活用することを検討してください。
プロジェクトの内容が分かる名前を選んでください。
プロジェクトが具体的に何ができるのかを人々に知らせましょう。背景を説明し、訪問者が馴染みがないかもしれない参考資料へのリンクを追加してください。機能のリストや「背景」というサブセクションをここに追加することもできます。プロジェクトに代替案がある場合は、ここで差別化要因を挙げるのが良いでしょう。
一部の README では、プロジェクトのすべてのテストが合格しているかどうかなど、メタデータを伝える小さな画像を見かけることがあります。Shields を使用して、README にバッジを追加できます。多くのサービスでは、バッジを追加するための手順も提供しています。
何を作っているかによっては、スクリーンショットや動画を含めると良いアイデアになる場合があります (実際の動画ではなく GIF をよく見かけます)。ttygif のようなツールも役立ちますが、より洗練された方法については Asciinema を確認してください。
特定のエコシステム内では、Yarn、NuGet、Homebrew などを使用するなど、ものをインストールする一般的な方法があるかもしれません。ただし、README を読んでいる人が初心者であり、より多くのガイダンスを求めている可能性があることを考慮してください。具体的な手順を列挙することで曖昧さがなくなり、人々ができるだけ早くプロジェクトを使い始められるようになります。特定のプログラミング言語のバージョンやオペレーティングシステムなど、特定のコンテキストでのみ動作する場合や、手動でインストールする必要がある依存関係がある場合は、「要件」サブセクションも追加してください。
例を惜しみなく使い、可能であれば期待される出力を示してください。実演できる最小の使用例をインラインで示すと役立ちます。また、より高度な例が長すぎて README に合理的に含められない場合は、それらへのリンクを提供してください。
人々が助けを求めるためにどこへ行けばよいかを伝えてください。イシュートラッカー、チャットルーム、メールアドレスなどの任意の組み合わせが可能です。
将来のリリースについてのアイデアがある場合は、README にそれらを列挙するのが良いでしょう。
コントリビューションを受け入れているかどうか、また受け入れるための要件を明記してください。
プロジェクトに変更を加えたい人にとって、始め方に関するドキュメントがあると役立ちます。実行すべきスクリプトや設定が必要な環境変数があるかもしれません。これらの手順を明示してください。この説明は将来の自分自身にも役立つことがあります。
コードの lint やテストの実行コマンドを文書化することもできます。これらの手順は、高いコード品質を確保し、変更が意図せず何かを壊してしまう可能性を減らすのに役立ちます。テストの実行手順は、ブラウザでのテストのために Selenium サーバーを起動するなど、外部のセットアップが必要な場合に特に役立ちます。
プロジェクトに貢献してくれた人々に感謝の意を示しましょう。
オープンソースプロジェクトの場合は、どのようにライセンスされているかを記載してください。
プロジェクトに取り組む気力や時間が尽きた、あるいは開発が減速または完全に停止した場合は、README の冒頭にその旨を記してください。誰かがあなたのプロジェクトをフォークしたり、メンテナーやオーナーとして自ら手を挙げたりするかもしれません。そうすることでプロジェクトを継続できます。メンテナーを明示的に募集することもできます。