Proposal: Strengthen Configuration and Dependency Change Approval

[wuhuizuo]

Strengthen Configuration and Dependency Change Approval

An approval process for changes to the file path scope of global variables, configurations, and dependencies will be deployed across all open-source product repositories.
We have already implemented this process for configuration change approval, and now we are expanding the scope to include dependency changes as well.

Why

Currently, the reviewers and approvers in the root OWNERS(such as OWNERS in tidb repo) file are for git repository granularity, and cannot fine-grained control over changes in important areas. Configuration/variable and dependency changes can have a wide-ranging impact, affecting system stability, compatibility, and performance. Recently, there have been several online issues caused by such changes.

To minimize the negative impact of configuration/variable and dependency changes, ensure that each change undergoes careful consideration and evaluation, comes with clear documentation, and reduces the risk of online issues, we plan to pilot pre-approval of these changes across all pingcap open-source repositories. We will delegate the approval responsibility to the person in charge of maintaining the respective products and the Dependency Management SIG.

What's new for developer

Same as before and no new actions introduced for the developers to perform. All the changes need to be approved by committers or maintainers as before except if there are configuration or dependency changes, the PRs need also to be approved by approvers inside the /OWNERS_ALIASES file. The approvers will be automatically recommended by a bot on GitHub.

Set up

1. Now we use Prow's OWNERS mechanism to control the approving for pull requests, here is the PR review flow.
2. We set up an OWNERS_ALIASES file in the root folder in each repository to maintain the approver teams for variable, configuration, and dependency changes.
3. We set up several OWNERS files in subfolders to support approving by folder or file paths. And make it not inherit from parent OWNERS files to ensure the changes must be approved by the dedicated approvers.
4. The changes should be approved by the matched approvers that are configured in OWNERS files (layer by layer in folder level), and leaf approvers first.
5. All the changes must be approved before merging.
6. OWNERS and OWNERS_ALIASES files should be updated on time.
7. If file paths need to be updated, we should update the OWNERS files in the leaf folders.
8. If the approver member should be updated, we should update the /OWNERS_ALIASES file.

Role and Responsibility

• For contributor
  • Assess the system's needs and requirements before making any configuration or dependency changes, considering factors such as performance, scalability, security, and compatibility.
  • Implement the configuration or dependency changes and verify that any changes made to the codebase or configuration maintain backward compatibility.
  • Conduct testing to verify the effects of configuration or dependency changes, checking for any adverse impact on system behavior, performance, or compatibility.
  • In case of any issues or unexpected outcomes resulting from the configuration or dependency changes, contributors actively troubleshoot and work towards resolving them.
  • Document the configuration parameters that affect user behavior and any system variable changes (adding, deleting, deprecating, modifying) by creating pull requests to documentation repositories (pingcap/docs, pingcap/docs-cn), adding the changes to release notes, and updating relevant documentation, to ensure that users have access to accurate and up-to-date information.
• For approver
  1. Thoroughly review all proposed configuration or dependency change pull requests. This involves examining the details of the proposed modifications, such as the purpose, impact, and potential risks associated with the configuration or dependency change.
  2. Evaluate the impact these changes may have on the system or any related components. This includes considering potential risks, such as performance impact, security vulnerabilities, or conflicts with existing configurations.
  3. Validate that the proposed configuration or dependency changes in the pull requests have undergone appropriate testing.
  4. Confirm the necessary documentation PR has been created.
  5. Grant approval for the PR.

Control Machinery for Dependency Changes

To ensure that dependency changes will not affect compatibility, stability, or performance, and are tested enough, we are introducing a new control mechanism.

1. Any changes made to go.mod files need to be approved by the Dependency Management SIG before merging.
2. The members of the Dependency Management SIG are defined in the /OWNERS_ALIASES file.
3. All the features of the control machinery are provided by Prow's OWNERS mechanism.
4. In the future, we will deploy similar control machinery to other repositories.

Deployment Plan for Dependency Changes

1. Initial Deployment:

   • We will first deploy the dependency control machinery to the tidb repository.
   • This includes setting up the necessary OWNERS and OWNERS_ALIASES files and ensuring the Dependency Management SIG is properly defined.

2. Future Deployment:

   • After successfully implementing the control machinery in the tidb repository, we will gradually roll out similar control mechanisms to other repositories within the pingcap and tikv organizations.
   • The rollout will be monitored and adjusted based on feedback and observed effectiveness.

By following this deployment plan, we aim to ensure a smooth transition and effective implementation of the control machinery across all open-source repositories.

[wuhuizuo]

Historical proposals in configuration change approval:

• Strengthen configuration change approval #45183
• https://github.com/orgs/pingcap/discussions/56125
• https://github.com/orgs/pingcap/discussions/56121