GitLab を使い始めるのが簡単になるよう、推奨される次のステップを以下に示します。
すでにプロですか?この README.md を編集して自分用にカスタマイズするだけです。簡単にしたいですか?下部のテンプレートを使用してください!
cd existing_repo
git remote add origin https://gitlab.com/valtersit/java-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 の冒頭にその旨を記してください。誰かがあなたのプロジェクトをフォークしたり、メンテナーやオーナーとして名乗り出ることを選ぶかもしれません。そうすることで、プロジェクトを継続できる可能性があります。また、メンテナーを明示的に募集することもできます。