# Design Doc: Community-driven RBS repository

## Glossaries

* PR author
* Who opens a pull request.
* Administrator (Admin)
* The administrator of ruby/gem_rbs_collection GitHub repository
* Including me (@pocke)
* Gem Reviewer
* A reviewer in charge of a gem
* It's specified in `gems/GEM_NAME/_reviewers.yaml`
* BOT
* The bot sends announcements, and merges pull requests.
* GHA
* GitHub Actions

## Requirements

### Minimize reviewing by admin (@pocke)

Currently @pocke reviews every PRs on gem_rbs_collection GitHub repository. I'd like to avoid this situation because @pocke is the bottleneck of this repository.

### Security

The following two requirements are guaranteed by this PR. https://github.com/ruby/gem_rbs_collection/pull/502

* The PR author MUST NOT execute arbitrary code on CI of the `main` branch.
* Therefore we need to give up executing RBS testing on runtime.
* The PR author MUST NOT execute arbitrary code on PC of RBS users.
* RBS related tools do not execute any program, therefore we do not need to care about it.

The following requirement is NOT guaranteed by the system. We just put a security policy and accept security reports.

* The PR author SHOULD NOT put malicious executable files
* The CI only executes limited files. Even if a malicious PR author puts an executable file, it does not affect anything if anyone execute it.
* But our GitHub repository should not provides malicious files. Therefore we should remove malicious files asap if they contamitate.

### First time contributors friendly

This repository should be friendly for the first time contributors too. This change make contribution easier because the contributor can do everything to merge the PR by themselves.

## Auto reviewing flow

The PR will be reviewed with the following flows. If multiple flows match, the PR must satisfy the all flow.

The admin can bypass the reviewing flow.

### Update an existing gem

1. The PR author opens a PR
2. If
1. The gem reviewers exist for the gem, and they do not include the PR author
1. The BOT requests reviewing to the gem reviewers
2. The gem reviewers review the PR until they approve it.
3. If the gem reviewers do not respond the request, the PR author can request to become a gem reviewer to the admin.
* See the Gem Reviewer Promotion section for more information
* After the request is accepted, it continues to the second flow.
4. After the gem reviewers approve it, the gem reviewer or the PR author can request merging the PR to the BOT.
5. The bot merges the PR.
2. The gem reviewers exist for the gem, and they include the PR author
1. The BOT requests reviewing to the gem reviewers
2. OPTIONAL: The gem reviewers review the PR until they approve it.
3. The gem reviewers can request merging the PR to the BOT.
4. The BOT merges the PR.
3. The gem reviewers do not exist for the tem
1. OPTIONAL: The PR author adds themselves to the gem reviewers.
2. If they adds, it continues to the second flow.
3. The PR author can request merging the PR to the BOT.
4. The BOT merges the PR.

### Add a new gem

1. The PR author opens a PR.
2. OPTIONAL: The PR author adds themselves to the gem reviewers.
3. The PR author can request merging the PR to the BOT.
4. The BOT merges the PR.

### Update / add non-gem files

1. The PR author opens a PR.
2. The BOT requets reviewing to the admin.
3. The admin reviews the PR until they approve it.
4. The admin or the BOT merges the PR.

## Gem Reviewer Promotion

(This section is under TODO. )

Basically, to become a gem reviewer requires approval from another gem reviewer of the gem or the admin.
It is necessary to avoid adding incorrect RBS files by a malicious PR author.

* If a PR author want to add a new gem, the PR author can become the gem reviewer of the gem without permission.
* If a PR author want to become a gem reviewer of an existing gem
* If the gem does not have any gem reviewers, the PR author can become a gem reviewer without permission.
* If the gem has gem reviewers, an approval is required from the gem reviewer.
* If the gem has reviewers but they are not active, the PR author can request the promotion to the admin.
* Admin can promote the PR author to the gem reviewer if the gem reviewer is absent TODO days.

If a gem reviewer does something malicious, the admin can ban them.

## How to implement

We use GHA for this purpose.
We need the following workflows.

### Testing

https://github.com/ruby/gem_rbs_collection/blob/main/.github/workflows/test.yml

We already have worflows for testing. It works on the pull_request event. We can use them continuously.

### Merge PR by a comment

When the PR author requests merging the PR on a PR comment, the BOT merges the PR.

This GHA workflow checks the PR is ready to be merged.

* The PR has necessary approvals.
* The user sending the comment has permission to the PR

This workflow also checks the following things inplicitly.

* The PR passes all tests
* It is checked by protected branch feature of GitHub
* The PR does not change `.github` directory
* It is checked CODEONWERS file
* This check is necessary to avoid falsification of GHA workflow files. If an attacker tries to falsificate GHA workflow, the PR needs to review by the admins.

This command uses the squash merge feature to avoid that a commit in the middle of the history contains malicious code. It is important to guarantee safety of `git bisect` and so on.

### Check that the PR has appropriate approval

It updates the commit status.

The commit status becomes green if the PR satisfies the all following conditions:

* If the PR changes files under `gems/`
* If `_reviewers.yaml` exists, it needs an approval from one of the Gem Reviewer or Admin.
* If `_reviewers.yaml` does not exists, it's satisfied.
* If the PR changes files under other directories
* It needs an approval from the Admin

### Request reviewing when PR opens and updated

It also needs to describe the role of the BOT.

## Migration process

This section describes how to migrate from the current system (using CODEOWNERS file).
We need to avoid attack on all phases during the migration.

1. Remove the users who are previously code owners from GitHub's outside collaborators.
* By this change, they lose code owner bit.
3. Configure code owner permission?
* Before merge the PR, we need to configure restriction on the GitHub UI (if we need)
* The protected branch is already configured. We do not need any action.
5. Merge https://github.com/ruby/gem_rbs_collection/pull/520
* The migration has been completed.

## Alternative Solutions

### Construct a server for the Bot

I decided to use GHA, but we can also use a server for the purpose. For example, we can build the bot as a Sinatra app and host it on Heroku. Or we can use serverless function service such as AWS Lambda.

But I have not decided using a server.

* I do not want to manage a server for this purpose.
* A server increases dependencies.
* Cost problem
* Heroku server or AWS Lambda can increases infrastructure cost.

## References

### GitHub Actions

* [Security hardening for GitHub Actions - docs.github.com](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions)
* [Automatic token authentication - docs.github.com](https://docs.github.com/en/actions/security-guides/automatic-token-authentication)
* https://blog.gitguardian.com/github-actions-security-cheat-sheet/
* It well describe security risks
* [Workflow syntax for GitHub Actions - docs.github.com](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)

### Related tools

* https://github.com/rubygems/bundlerbot
* Bundler previously used this script to merge PRs, but currently they are not used it.
* It uses GitHub app
* https://github.com/DefinitelyTyped/dt-mergebot
* DefinitelyTyped uses this bot.