Skip to content

COLLABORATOR_GUIDE.md

Latest commit

 

History

History
286 lines (215 loc) · 12.8 KB

COLLABORATOR_GUIDE.md

File metadata and controls

286 lines (215 loc) · 12.8 KB

Obsoletium collaborator guide

Contents

This document explains how collaborators manage the Obsoletium project. Collaborators should understand the guidelines for new contributors.

Issues and pull requests

Mind these guidelines and the opinions of other collaborators. Notify other qualified parties for more input on an issue or a pull request. See Who to CC in the issue tracker.

Welcoming first-time contributors

Always show courtesy to individuals submitting issues and pull requests. Be welcoming to first-time contributors, identified by the GitHub First-time contributor badge.

For first-time contributors, check if the commit author is the same as the pull request author. This way, once their pull request lands, GitHub will show them as a Contributor. Ask if they have configured their git username and email to their liking.

Closing issues and pull requests

Collaborators can close any issue or pull request that is not relevant to the future of the Obsoletium project. Where this is unclear, leave the issue or pull request open for several days to allow for discussion. Where this does not yield evidence that the issue or pull request has relevance, close it. Remember that issues and pull requests can always be re-opened if necessary.

Author ready pull requests

A pull request is author ready when:

  • There is a CI run in progress or completed.
  • There is at least one collaborator approval.
  • There are no outstanding review comments.

Please always add the author ready label to the pull request in that case. Please always remove it again as soon as the conditions are not met anymore.

Handling own pull requests

When you open a pull request, start a CI right away. Later, after new code changes or rebasing, start a new CI.

As soon as the pull request is ready to land, please do so. This allows other collaborators to focus on other pull requests. If your pull request is not ready to land but is author ready, add the author ready label. If you wish to land the pull request yourself, use the "assign yourself" link to self-assign it.

Managing security issues

Use the process outlined in SECURITY.md to report security issues. If a user opens a security issue in the public repository:

  • Ask the user to submit a report through secure.whitebox.authors@gmail.com as outlined in SECURITY.md.
  • Move the issue to the private repository called premature-disclosures.
  • For any related pull requests, create an associated issue in the premature-disclosures repository. Add a copy of the patch for the pull request to the issue. Add screenshots of discussion from the pull request to the issue.
  • Open a ticket with GitHub to delete the pull request using Source-Authors (team) as the account organization.
  • Open a new issue in the public repository with the title FYI - pull request deleted #YYYY. Include an explanation for the user:

    FYI @xxxx we asked GitHub to delete your pull request while we work on releases in private.

Accepting modifications

Contributors propose modifications to Obsoletium using GitHub pull requests. A pull request must pass code review and CI before landing into the codebase.

Code reviews

At least one collaborator must approve a pull request before the pull request lands.

Approving a pull request indicates that the collaborator accepts responsibility for the change.

Approval must be from collaborators who are not authors of the change.

Ideally pull requests for dependencies should be generated by automation. Pay special attention to pull requests for dependencies which have not been automatically generated.

In some cases, it might be necessary to summon a GitHub team to a pull request for review by @-mention. See Who to CC in the issue tracker.

If you are the first collaborator to approve a pull request that has no CI yet, please start one. Please also start a new CI if the pull request creator pushed new code since the last CI run.

Consensus seeking

A pull request can land if it has the needed approvals, CI, wait time and no outstanding objections. If a pull request meets all requirements except the wait time, please add the author ready label.

Objections

Collaborators can object to a pull request by using the "Request Changes" GitHub feature. Dissent comments alone don't constitute an objection, nor do dissenting comments made in any associated issue. A blocking objection to a change must be made in the pull request that specifically proposes that change. Any pull request objection must include a clear reason for that objection, and the objector must remain responsive for further discussion towards consensus about the direction of the pull request. Where possible, provide a set of actionable steps alongside the objection.

If the objection is not clear to others, another collaborator can ask an objecting collaborator to explain their objection or to provide actionable steps to resolve the objection. If the objector is unresponsive for seven days after a collaborator asks for clarification, a collaborator may dismiss the objection.

Pull requests with outstanding objections must remain open until all objections are satisfied.

All Collaborator objections are considered equal.

Mistakes do happen. If a pull request is merged with an unresolved objection, submit a fix. Simple issues may be fixed with a follow-up PR that addresses the concern. More difficult issues may require a full revert. Most corrections can be fast-tracked. If deemed necessary take a slower route to ensure stability and consensus.

Collaborators objecting to a pull request can best ensure their objections are addressed by remaining engaged and responsive in the discussion.

Helpful resources

Waiting for approvals

Before landing pull requests, allow 48 hours for input from other collaborators. Certain types of pull requests can be fast-tracked and can land after a shorter delay. For example:

  • Focused changes that affect only documentation and/or the test suite:
    • good-first-issue tasks often fall into this category.
  • Changes that fix regressions:
    • Regressions that break the workflow (red CI or broken compilation).
    • Regressions that happen right before a release, or reported soon after.

To propose fast-tracking a pull request, apply the fast-track label.

If someone disagrees with the fast-tracking request, remove the label. Do not fast-track the pull request in that case.

The pull request can be fast-tracked if one collaborator approve the fast-tracking request. To land, the pull request itself still needs one collaborator approvals and a passing CI.

Collaborators can request fast-tracking of pull requests they did not author. In that case only, the request itself is also one fast-track approval.

Testing and CI

All fixes must have a test case which demonstrates the defect. The test should fail before the change, and pass after the change.

Do not land any pull requests without the necessary passing CI runs. A passing (green) GitHub Actions CI result is required.

If there are GitHub Actions CI failures unrelated to the change in the pull request, try the "🔄 Re-run all jobs" button, on the right-hand side of the "Checks" tab.

Reverting commits

Revert commits with git revert <HASH> or git revert <FROM>..<TO>. The generated commit message will not have a subsystem and might violate line length rules. That is OK. Append the reason for the revert. Raise a pull request like any other change.

Landing pull requests

  1. Avoid landing pull requests that have someone else as an assignee. Authors who wish to land their own pull requests will self-assign them. Sometimes, an author will delegate to someone else. If in doubt, ask the assignee whether it is okay to land.
  2. Make sure CI is complete and green. If the CI is not green, check for unreliable tests and infrastructure failures. If there are no corresponding issues, open new issues. Run a new CI any time someone pushes new code to the pull request.
  3. Check that the commit message adheres to commit message guidelines.
  4. Use GitHub's green "Merge pull request" button.

For pull requests from first-time contributors, be welcoming. Also, verify that their git settings are to their liking.

If a pull request contains more than one commit, it can be landed either by squashing into one commit or by rebasing all the commits, or a mix of the two. Generally, a collaborator should land a pull request by squashing. If a pull request has more than one self-contained subsystem commits, a collaborator may land it as several commits.

All commits should be self-contained, meaning every commit should pass all tests. This makes it much easier when bisecting to find a breaking change.

I made a mistake

  • Ping responsible collaborator. See Who to CC in the issue tracker.
  • With git, there's a way to override remote trees by force pushing (git push -f). This is generally forbidden as it creates conflicts in other people's forks. It is permissible for simpler slip-ups such as typos in commit messages. You are only allowed to force push to any Obsoletium branch within 10 minutes from your original push. If someone else pushes to the branch or the 10-minute period passes, consider the commit final.
    • Use --force-with-lease to reduce the chance of overwriting someone else's change.

Who to CC in the issue tracker

If you cannot find who to cc for a file, git shortlog -n -s <file> can help.

Labels

General labels

  • confirmed-bug: Bugs you have verified
  • discuss: Things that need larger discussion
  • fast-track: PRs that need to land faster - see Waiting for approvals
  • feature request: Any issue that requests a new feature
  • good first issue: Issues suitable for newcomers to fix
  • meta: Governance, policies, procedures, etc.
  • author-ready - A pull request is author ready when:
    • There is a CI run in progress or completed.
    • There is at least one collaborator approval.
    • There are no outstanding review comments.

Please always add the author ready label to pull requests that qualify. Please always remove it again as soon as the conditions are not met anymore, such as if the CI run fails or a new outstanding review comment is posted.

Other labels

  • Operating system labels
    • macos, windows, freebsd, linux, etc.
  • Architecture labels
    • arm64, risc-v, etc.
    • No x86{_64} label because it is the implied default