コントリビューションガイドは OSS 以外でも導入すべき

GitHub などで管理・公開されている OSS プロジェクトで CONTRIBUTING.md というファイルをよく見かけます。このファイルは、プロジェクトに対するコミットメントの方法、ルール、あるいはガイドラインがコントリビューター向けとして記載されたものです。

筆者は少し前から Node.js パッケージの開発・保守をするようになり、その過程で CONTRIBUTING.md について調べ、これを導入したのですが、このドキュメントは OSS 以外（例えば企業の web サービスなど）のプロジェクトでも導入する価値があると感じました。

コントリビューションガイドの基礎知識

コントリビューションガイドとは、そのリポジトリー（= プロジェクト）に関わるすべての人が適切に作業を行う上で役立つ情報を提供するためのドキュメントです。

Git および GitHub 上などでの開発には、コミットメッセージの書き方、ブランチの命名規則、Pull Request の作成方法、コードレビューの方法、コードのフォーマット、テストの実行方法など、多種多様なノウハウが存在します。リポジトリーのオーナーは自身が考える最適なフローに準じて開発を進めますが、外部のコントリビューターがそのフローに従ってコミットしてくれるとは限りません。もし一見のコントリビューターがリポジトリーで（暗黙的に）定められたルールに準じていないコミットを行った場合、オーナーはそのコミットを受け入れるか、拒否するか、あるいは修正を求めるかを決定しなければなりません。このような状況はオーナーにとって望ましくないものです。

オーナーおよびコントリビューターの双方にとって、コントリビューションガイドは Pull Request や Issue のリジェクトや再提出の手間を未然に軽減するために有効な手段です。また、プロジェクトへのコミットメントを検討している人々に対して何が期待されているかを明確に伝える機能も果たします。

OSS 以外の開発プロジェクトにも導入すべき理由

コントリビューションガイドは OSS 文化圏においては一般的なものですが、企業の自社サービスといった開発プロジェクトにも導入する価値があると考えます。以下にその理由を示します。

明確な期待値の設定

コントリビューションガイドは、コントリビューターに対してプロジェクトに対する期待値を明確に伝えます。これによって、コントリビューターはプロジェクトに対する貢献を行う際に、オーナーが求める品質やスタイルに準じた作業を行うことができます。これには、コードのスタイル、テストの要件、ドキュメントの更新などが含まれます。

新人教育の効率化

コントリビューションガイドは、新人や新たに異動してきた者がチームに参画する際に彼らが必要とする情報を提供し、迅速に作業を開始できるようにするオンボーディングの資料として機能します。

コード品質の向上

ガイドラインを理解し、これに従うことでコードの品質と一貫性、git commit ならびに Pull Request の粒度の担保が維持されることでコードレビューの時間が節約され、将来のメンテナンスを容易にします。

コミュニケーションの円滑化

明確なコントリビューションプロセスは開発者間のコミュニケーションを改善し、誤解や重複した作業を削減します。

作り方

コントリビューションガイドは、リポジトリーのルートディレクトリーもしくは .github ディレクトリーに CONTRIBUTING.md というファイル名で配置されることが一般的です。こうすることで GitHub では Pull Request や Issue を作成する際に、コントリビューターにこのファイルを参照するよう促すメッセージとリンクが表示されます。

コントリビューションガイドに決まったフォーマットはありませんが、以下の内容を含むのが一般的です。

• 必要となる開発環境の情報
• Getting Started セクション
  • 開発環境のセットアップ方法
  • 開発過程で使用するコマンドとその説明
• How to Contribute セクション
  • バグ報告や機能リクエストの方法
  • 開発の手順
  • コミットメッセージの書き方
  • コードスタイル
  • テスト方法
  • プルリクエストの作成方法
• License セクション

`CONTRIBUTING.md` の例（英語版）

CONTRIBUTING.md

# Contributing to [Project Name]

I appreciate your consideration to contribute to this project! This document is a guide to help make your contribution easier and more effective.

## Getting Started

### Prerequisites

- [Node.js](https://nodejs.org) (See [`.node-version`](/.node-version))

### Installation

1. Clone the repository

    ```bash
    git clone https://github.com/your-username/repository-name.git
    ```

2. Move to the directory and install dependencies

    ```bash
    cd repository-name
    npm install
    ```

### Development

The main scripts used during development are:

- `npm run lint`: Runs lint on your code.
- `npm run test`: Runs unit tests.

## How to Contribute

### Reporting Issues

If you find a bug or have a feature request, please open an issue on GitHub.

1. Check [the Issue Tracker](https://github.com/owner-name/repository-name/issues) for existing issues.
2. When requesting a new issue or feature, please use [the templates](https://github.com/owner-name/repository-name/issues/new/choose) and provide as much detail as possible.

### Development

1. Check [the Issue Tracker](https://github.com/owner-name/repository-name/issues), make sure if there is anything relevant to the problem you are trying to solve.
2. Keep the repository you did folk up to date.

   ```bash
    git fetch upstream
    git rebase upstream/main
   ```

3. Create a new branch.

   ```bash
   git switch -c feature/your-feature-name
   ```

4. Make changes to the code and run tests to make sure everything is working properly.
5. Write a clear commit message.

### Commit Messages

- Commit messages should concisely describe the changes you made.
- Commits should be split into appropriate chunks, and we recommend using [the Conventional Commits](https://www.conventionalcommits.org/) style. Below are the available Conventional Commits types:
  - `feat`: a commit that adds new functionality.
  - `fix`: a commit that fixes a bug.
  - `docs`: a commit that adds or improves a documentation.
  - `style`: changes that do not affect the meaning of the code.
  - `refactor`: a code change that neither fixes a bug nor adds a feature.
  - `perf`: a commit that improves performance, without functional changes.
  - `test`: adding missing tests or correcting existing tests.
  - `build`: changes that affect the build system or external dependencies.
  - `ci`: changes to our CI configuration files and scripts.
  - `chore`: other changes that don't modify src or test files.
  - `revert`: reverts a previous commit.

> [!NOTE]
> If there is a single commit in the pull request, the commit message must be the same as a pull request title. Because the merge strategy in this repository is "Squash and merge". When you "Squash and merge" a pull request on a branch that has only one commit, the default commit message will be the commit message in that branch.
>
> cf. [About pull request merges - GitHub Docs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#merge-message-for-a-squash-merge)

### Code Style

- Code according to [ESlint](/eslint.config.js) and [Prettier](/prettier.config.js) rules.
- Keep your code in a consistent style.

### Testing

- If you make changes, add unit tests or make sure that the existing tests pass.
- Tests are powered by [Vitest](https://vitest.dev/). When adding tests, try to increase test coverage.

### Pull Requests

1. Write the title of pull request in the [the Conventional Commits](https://www.conventionalcommits.org/) style. Below are the available Conventional Commits types:
   - `feat`: a commit that adds new functionality.
   - `fix`: a commit that fixes a bug.
   - `docs`: a commit that adds or improves a documentation.
   - `style`: changes that do not affect the meaning of the code.
   - `refactor`: a code change that neither fixes a bug nor adds a feature.
   - `perf`: a commit that improves performance, without functional changes.
   - `test`: adding missing tests or correcting existing tests.
   - `build`: changes that affect the build system or external dependencies.
   - `ci`: changes to our CI configuration files and scripts.
   - `chore`: other changes that don't modify src or test files.
   - `revert`: reverts a previous commit.
2. Create a pull request and include the following information:
   - Description of the change
   - Purpose of the change
   - Relevant issue number (if any)

## License

This project is based on [MIT License](/LICENSE).

FAQ

Q. Notion や Confluence などの Wiki 系ツールで十分ではないか？

A. 確かにこの類のドキュメントは Wiki 系ツールを使用して管理されることが多いですが、コントリビューションガイドはリポジトリー内に配置されることでコントリビューターがプロジェクトに対する期待値を容易に参照できるようになります。Wiki ツールではリポジトリーから離れた場所に配置されるため、コントリビューターが見落とす可能性があります。

また、 CONTRIBUTING.md として Git リポジトリーで管理すればソースコードと同じ要領で更新履歴を管理・追跡できるだけでなく、Pull Request や Issue を通じて更新内容を議論することもできます。

Q. コントリビューションガイドはどのようにメンテナンスされるべきか？

A. コントリビューションガイドはプロジェクトの変更に合わせて定期的に更新されるべきです。新しい機能や変更が追加された場合、それに対応するための手順やルールを追加する必要があります。また、プロジェクトのメンテナンスを行う際に、コントリビューションガイドも併せて更新することで、新人を含むコントリビューターが最新の情報を参照できるようにします。

締め

企業の自社サービスといった開発は OSS プロジェクトと異なり、プロジェクトのアクセス権が限定された内輪の開発者によって行われることが普通ですが、コントリビューションガイドはチームの効率と生産性を高めるための重要なツールとして機能します。企業内の開発チームも、OSS プロジェクトから学んだベストプラクティスを取り入れることで、より効果的な開発プロセスを構築できることでしょう。

参考文献

https://docs.github.com/ja/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors