From afb8f06d95bb219eeeea100372a16b944851776e Mon Sep 17 00:00:00 2001 From: Gautam Sharda Date: Mon, 30 Mar 2026 19:41:16 +0000 Subject: [PATCH] chore: update contributing guide to match librarian --- CONTRIBUTING.md | 358 ++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 329 insertions(+), 29 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 78aaa61b269..cc3e05964e0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,40 +1,340 @@ -# How to become a contributor and submit your own code +# How to Contribute -**Table of contents** +We'd love to accept your patches and contributions to this project. There are +just a few small guidelines you need to follow. -* [Contributor License Agreements](#contributor-license-agreements) -* [Contributing a patch](#contributing-a-patch) -* [Running the tests](#running-the-tests) -* [Releasing the library](#releasing-the-library) +## Contributor License Agreement -## Contributor License Agreements +Contributions to this project must be accompanied by a Contributor License +Agreement. You (or your employer) retain the copyright to your contribution; +this simply gives us permission to use and redistribute your contributions as +part of the project. Head over to to see +your current agreements on file or to sign a new one. -We'd love to accept your sample apps and patches! Before we can take them, we -have to jump a couple of legal hurdles. +You generally only need to submit a CLA once, so if you've already submitted one +(even if it was for a different project), you probably don't need to do it +again. -Please fill out either the individual or corporate Contributor License Agreement -(CLA). +## Code Reviews - * If you are an individual writing original source code and you're sure you - own the intellectual property, then you'll need to sign an [individual CLA](https://developers.google.com/open-source/cla/individual). - * If you work for a company that wants to allow you to contribute your work, - then you'll need to sign a [corporate CLA](https://developers.google.com/open-source/cla/corporate). +All submissions, including submissions by project members, require review. We +use GitHub pull requests for this purpose. Submissions by non-Googlers require +two reviewers. Consult +[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more +information on using pull requests. -Follow either of the two links above to access the appropriate CLA and -instructions for how to sign and return it. Once we receive it, we'll be able to -accept your pull requests. -## Contributing A Patch +### Multi-Approvers Check -1. Submit an issue describing your proposed change to the repo in question. -1. The repo owner will respond to your issue promptly. -1. If your proposed change is accepted, and you haven't already done so, sign a - Contributor License Agreement (see details above). -1. Fork the desired repo, develop and test your code changes. -1. Ensure that your code adheres to the existing style in the code to which - you are contributing. -1. Ensure that your code has an appropriate set of tests which all pass. -1. Submit a pull request. +Each pull request must be approved by two Googlers. This is enforced by an +automated multi-approvers check. This check may not automatically re-run +after the second approval is added. If it remains in a failed state, you +can manually re-trigger it by: + +1. Clicking "View details" on the failed workflow to bring you to the "Actions" page. +2. Clicking "Re-run failed jobs". + +For more information, see +[Re-running failed jobs in a workflow](https://docs.github.com/en/actions/how-tos/managing-workflow-runs-and-deployments/managing-workflow-runs/re-running-workflows-and-jobs#re-running-failed-jobs-in-a-workflow). + +## Community Guidelines + +This project follows +[Google's Open Source Community Guidelines](https://opensource.google/conduct/). + +--- + +The section above follows the standard googleapis organization’s +CONTRIBUTING.md template. The section below is specific to this +project. It explains how we work, how we use GitHub, and what contributors can +expect when engaging with this repository. + +--- + +## Before contributing code + +Before doing any significant work, open an issue to propose your idea and +ensure alignment. You can either file a new issue, or comment on an existing one. + +A pull request (PR) that does not go through this coordination process may be +closed to avoid wasted effort. + +## Checking the issue tracker + +We use GitHub issues to track tasks, bugs, and discussions. + +> _If it didn’t happen in a GitHub issue, it never happened._ + +Use the issue tracker as your source of truth. + +## Filing a new issue + +All changes, except trivial ones, should start with a GitHub issue. + +This process gives everyone a chance to validate the design, helps prevent +duplication of effort, and ensures that the idea fits inside the goals for the +language and tools. It also checks that the design is sound before code is +written; the code review tool is not the place for high-level discussions. + +Always include a clear description in the body of the issue. The description +should provide enough context for any team member to understand the problem or +request without needing to contact you directly for clarification. + +## Leaving a TODO + +When adding a TODO to the codebase, always include a link to an issue, no +matter how small the task. + +Use the format: + +``` +// TODO(https://github.com/googleapis/google-cloud-node/issues/): explain what needs to be done +``` + +This helps provide context for future readers and keeps the TODO relevant and +actionable as the project evolves. + +## Sending a pull request + +All code changes must go through a pull request. First-time contributors should +review +[GitHub flow](https://docs.github.com/en/get-started/using-github/github-flow). + +Before sending a pull request, it should include tests if there are logic +changes, copyright headers in every file, and a commit message following the +conventions in "Commit messages" section below. + +A pull request can be opened from a branch within the repository or from a +fork. External contributors are only able to open pull requests from forks, +but team members with write access can choose to open a pull request from a +repository branch. + +### Pull request from a fork + +If you open a pull request from a personal fork, you should allow repository +maintainers to make edits to your fork by turning on +"Allow edits from maintainers". + +Please see [creating a pull request from a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) +in the official GitHub documentation for details. + +### Pull request from a branch + +If you are a team member with write access, you can create a branch within the +repository with your changes and open a pull request from it. After the pull +request is merged, the branch will be automatically deleted. + +You should not have any long-lived branches within the repository without an +open pull request. Such non-protected branches that don't have an associated +open pull request, will be periodically cleaned up. + +### Pull requests with multiple commits + +When opening a pull request, it can be helpful to structure the commits for review. If +your pull request has multiple commits, note in the description whether reviewers should +review them individually or just focus on the final result. (For example, if +earlier commits are exploratory and only the end state matters, make that clear +to avoid wasting reviewer time.) + +### Keeping pull requests up to date with base branch + +The repository is configured to not require branches to be up to date before merging. +This means that you do not have to have the latest changes from the base branch +integrated, unless GitHub detects merge conflicts. + +To minimize the risk of the pull request getting out of date with the base branch, enable +[auto-merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request) +so that the pull request submits as soon as it is approved and the checks pass. + +## Commit messages + +Commit messages follow the conventions below. + +Here is an example: + +``` +feat(storage): add new storage bucket feature + +A new feature is added to storage. + +Fixes #238 +``` + +### First line + +The first line of the change description is a short one-line summary of the +change, following the structure `(): `: + +#### type + +A structural element defined by the conventions at +https://www.conventionalcommits.org/en/v1.0.0/#summary. + +Conventional commits are parsed by release tooling to +generate release notes. + +#### package + +The name of the package affected by the change, and should be provided in +parentheses before the colon. (For example, `storage` or `pubsub`). + +#### description + +A short one-line summary of the change, that it should be written so to complete +the sentence "This change modifies the codebase to ..." That means it does not +start with a capital letter, is not a complete sentence, and actually +summarizes the result of the change. Note that the verb after the colon is +lowercase, and there is no trailing period. + +The first line should be kept as short as possible (many git viewing tools +prefer under ~76 characters). + +Follow the first line by a blank line. + +### Main content + +The rest of the commit message should provide context for the change and +explain what it does. Write in complete sentences with correct punctuation. +Don't use HTML, Markdown, or any other markup language. + +### Referencing issues + +The special notation "Fixes #12345" associates the change with issue 12345 in +the issue tracker. When this change is eventually applied, the issue +tracker will automatically mark the issue as fixed. + +If the change is a partial step towards the resolution of the issue, write +"For #12345" instead. This will leave a comment in the issue linking back +to the pull request, but it will not close the issue when the change is +applied. + +Please don’t use alternate GitHub-supported aliases like Close or Resolves +instead of Fixes. + +## The review process + +This section explains the review process in detail and how to approach reviews +after a pull request has been sent for review. + +### Getting a code review + +Before creating a pull request, make sure that your commit message follows the +suggested format. Otherwise, it can be common for the pull request to be sent +back with that request without review. + +After creating a pull request, request a specific reviewer if relevant, or leave it for +the default group. + +### Merging a pull request + +Pull request titles and descriptions must follow the [commit messages](#commit-messages) +conventions. This enables approvers to review the final commit message. Once the pull +request has been approved and all checks have passed, click the +[Squash and Merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-commits) +button. The resulting commit message will be based on the pull request's title and +description. + +### Reverting a pull request + +If a merged pull request needs to be undone, for reasons such as breaking the build, the +standard process is to [revert it through the GitHub interface](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/reverting-a-pull-request). + +To revert a pull request: +1. Navigate to the merged pull request on GitHub. +2. Click the **Revert** button. This action automatically creates a new branch and a pull request containing the revert commit. +3. Edit the pull request title and description to comply with the [commit message guidelines](#commit-messages). +4. The newly created revert pull request should be reviewed and merged following the same process as any other pull request. + +Using the GitHub "Revert" button is the preferred method over manually creating a revert commit using `git revert`. + +### Keeping the pull request dashboard clean + +We aim to keep the pull requests page clean so that we +can quickly notice and review incoming changes that require attention. + +Given that goal, please do not open a pull request unless you are ready for a +code review. Draft pull requests and ones without author activity for more than +one business day may be closed (they can always be reopened later). + +If you're still working on something, continue iterating on your branch without +creating a pull request until it’s ready for review. + +### Addressing code review comments + +Creating additional commits to address reviewer feedback is generally preferred +over amending and force-pushing. This makes it easier for reviewers to see what +has changed since their last review. + +Pull requests are always squashed and merged. Before merging, please review and +edit the resulting commit message to ensure it clearly describes the change. + +After pushing, +[click the button](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review#requesting-reviews-from-collaborators-and-organization-members) +to ask a reviewer to re-request your review. + +## Expectations for the team + +A lot of our communication will happen on GitHub issues. Team members are +expected to configure their inboxes to receive GitHub notifications alerts for +all issues and pull requests to ensure effective communication. + +If a pull request becomes inactive or misaligned with current priorities, we +may close it to respect contributor and reviewer time. If you’d like to revisit +it, just comment and reopen the conversation. + +If your pull request or issue is stuck, feel free to follow up over chat. We +encourage it! + +### Reviewing a pull request + +When reviewing a pull request: + +- Start by reading the PR description to understand the purpose and context. If + the commit message doesn’t follow the + [commit message guidelines](#commit-messages), + request changes. +- Use `Approve` or `Request changes` explicitly. Avoid leaving ambiguous + feedback. +- Focus on what is in scope. If unrelated issues arise, suggest filing a + separate PR or issue. +- If you’ve requested changes, approve the PR once the updates are + satisfactory, even if the author forgot to click the re-request review. +- If a review has stalled or the context has shifted, leave a comment to + clarify expectations, or close the PR. Keeping the dashboard clean is encouraged. + +### Addressing Urgent Issues + +We categorize issues into two primary levels of urgency: + +- **critical 🚨**: requires immediate fix, even outside business hours +- **needs fix soon ❗**: high priority issue, can be fixed during business hours + +When an issue is labeled `critical 🚨`, the priority is to stabilize the system +enough to downgrade the severity to `needs fix soon ❗`. + +### Maintaining a Healthy Main Branch + +All pull requests require passing CI checks to be merged. + +The main branch must always be stable, and tests should never fail at HEAD. A +red build on the main branch is a critical issue that must be fixed immediately. + +If tests become flaky or the main branch is not consistently green, the team's top priority +should shift to restoring stability. All feature development should be +deprioritized until green builds can be guaranteed. + +When you see a red x next to a commit on main, file an issue on your GitHub +issue tracker, and label it `critical 🚨`. + +Create a PR to temporarily skip the test, and verify that you have a green +checkmark next to the commit on your main branch. The issue can now be +downgraded to `needs fix soon ❗`. + +### Handling Dependency Updates + +We only update dependencies for security vulnerabilities, bug fixes, or to add +feature support. Security vulnerabilities are identified using Dependabot or `npm audit`. Dependency updates for bug fixes or new features must be associated +with an issue in this repository. ## Running the tests @@ -52,4 +352,4 @@ accept your pull requests. npm run fix -[setup]: https://cloud.google.com/nodejs/docs/setup +[setup]: https://cloud.google.com/nodejs/docs/setup \ No newline at end of file