Skip to content

Latest commit

 

History

History
171 lines (139 loc) · 10.6 KB

pull-requests.md

File metadata and controls

171 lines (139 loc) · 10.6 KB
Raw

Pull Requests

This document clarifies rules and expectations of contributing and reviewing pull requests. It is structured as a list of rules which can be referenced on a PR to moderate and drive discussions. If a rule causes distress during discussions itself, it has to be reviewed on the dev meeting and updated.

Opening a Pull Request

  • 1. Each PR description has to follow the following template:

    <!--
Thank you for your Pull Request. Please provide a description and review
the requirements below.

Contributors guide: https://github.com/eclipse-theia/theia/blob/master/CONTRIBUTING.md
-->

#### What it does
<!-- Include relevant issues and describe how they are addressed. -->

#### How to test
<!-- Explain how a reviewer can reproduce a bug, test new functionality or verify performance improvements. -->

#### Review checklist

- [ ] As an author, I have thoroughly tested my changes and carefully followed [the review guidelines](https://github.com/eclipse-theia/theia/blob/master/doc/pull-requests.md#requesting-a-review)

#### Reminder for reviewers

- As a reviewer, I agree to review in accordance with [the review guidelines](https://github.com/eclipse-theia/theia/blob/master/doc/pull-requests.md#reviewing)

  • 2. A PR can be opened early for the design review before going into the detailed implementation.
    • A request on the design review should be an explicit comment.
    • Such PR should be marked as a draft or with the WIP prefix.

  • 3. Changes done after the PR has been opened should be kept in separate commits until the review process is finished. This allows reviewers to re-review only the updated parts of the PR and to determine what needs to be tested again. The "fixup" commits must be squashed before merging in order to keep a clean history.

Requesting a Review

  • 1. A review can be requested when:
  • 2. A review can be requested explicitly using GitHub.
  • 3. A review can be also requested as a comment from any GitHub users.
    • For example to invite the person who originally filed an issue for testing.

Review Checklist

  • 1. The new code is built and tested according to the How to test section of a PR description.
  • 2. The new code is aligned with the project organization and coding conventions.
  • 3. Changelog is updated.
  • 4. Breaking changes are justified and recorded in the changelog.
  • 5. New dependencies are justified and verified.
  • 6. Copied code is justified and approved via a CQ.
    • Look closely at the GitHub actions running for your PR: the 3pp/dash license check should be green.
    • If red: it most likely mean you need to create a CQ.
  • 7. Each new file has proper copyright with the current year and the name of contributing entity (individual or company).
  • 8. Commits are signed-off: https://github.com/eclipse-theia/theia/blob/master/CONTRIBUTING.md#sign-your-work.
  • 9. Each commit has meaningful title and a body that explains what it does. One can take inspiration from the What it does section from the PR.
  • 10. Commit history is rebased on master and contains only meaningful commits and changes (less are usually better).
    • For example, use git pull -r or git fetch && git rebase to pick up changes from the master.

Reviewing

  • 1. Reviewers should check that a PR has a proper description.
  • 2. Reviewers should build and verify changes according to the How to test section of a PR description.
  • 3. Reviewers should ensure that all checks from the review checklist are successful.
  • 4. A reviewer does not need to ensure everything but can verify a part of it and provide feedback as a comment.
  • 5. For any change that substantially alters the behavior of the application or one of its components, reviews should be requested from representatives of several contributing organizations to ensure consistency with the goals of the project and compatibility with significant adopters' downstream products.

Requesting Changes

  • 1. Changes should be requested if an author does not follow the review requirements.
  • 2. Changes cannot be requested because of the personal preferences of a reviewer.
    • Such change requests should be dismissed.
  • 3. Changes cannot be requested if they address issues out of the scope of a PR.
    • Such change requests should be dismissed and an issue should be filed to address them separately.
  • 4. Styles and coding preferences should not be discussed on the PR, but raised in the dev meeting, agreed by the team, applied to the coding guidelines and after that followed by all contributors.

Approving

  • 1. Each approval should have supporting comments following these guidelines.
  • 2. An approval without a comment should be dismissed.
  • 3. Approval of a PR implies that the reviewer is prepared to merge the PR. A reviewer should only approve a pull request that they are prepared to merge it. If a PR is under review by multiple reviewers, reviewers who are not satisfied with the state of the PR should block its merge, for example by marking their review 'request changes'.

Collaborating

  • 1. If a change request is important, but cannot be elaborated by a reviewer, then a reviewer should be encouraged to open an alternative PR or collaborate on a current PR.
  • 2. If a PR is important, but an author cannot or does not want to address outstanding issues, then maintainers can complete the PR with additional commits provided that the original author accepted the ECA and their commits are preserved - the original author's work should not be squashed away.
  • 3. Reviewers should offer their help via a comment to avoid intervening in an author's work.
  • 4. Such comment is not required if an author is not responsive.

Landing

  • 1. A PR can be landed when:
  • 2. Pull requests satisfying the criteria above should be merged in a timely fashion to avoid a buildup of approved PR's at release time. Responsibility for merging a PR falls to
    • The author, if the author is a committer.
    • A committer from the author's organization, if one is available.
    • The approving reviewer, otherwise.

Reverting

  • 1. If a PR causes regressions after landing then an author and maintainers have 2 days to resolve them after that a PR has to be reverted.

Closing

  • 1. A reviewer cannot close a PR without a reason.
  • 2. A PR may be closed, for example, because of the following reasons:
    • It introduces functionality which should be implemented as external Theia or VS Code extensions.
    • It introduces structural or API changes between core extensions. Such changes have to be done by an experienced maintainer to avoid regressions and long reviews.
    • It should be a 3rd party component, e.g. Theia is not a logging framework or a proxy server.
    • It changes development infrastructure, e.g. testing frameworks, packaging and so on. Such changes have to be done by active maintainers after agreement in the dev meeting.