get.porter.sh/porter@v1.3.0/REVIEWING.md (about)

     1  # Reviewing Guide
     2  
     3  * [Values](#values)
     4  * [How to review a pull request](#how-to-review-a-pull-request)
     5    * [Giving feedback](#giving-feedback)
     6  * [Cut a release](#cut-a-release)
     7  
     8  
     9  # Values
    10  
    11  Thank you for reviewing pull requests for us! 💖
    12  
    13  Here are the values and etiquette that we follow to ensure a welcoming, inclusive
    14  project that doesn't burn out our authors or our reviewers. 😅
    15  
    16  * We ask that authors respect reviewers' time. Check out the
    17    [Contributing Guide](CONTRIBUTING.md) and know that you can ask the
    18    author to do their part to make _your_ part manageable.
    19  * We ask that reviewers respect authors' time. Please do your best to review
    20    a pull request in a reasonable amount of time once you have assigned it to
    21    yourself.
    22  * The definition of "reasonable amount of time" is 3 business days. The ask is
    23    that after each trigger: "Review Requested", "Changes Incorporated", etc that
    24    the other person attempt to do their part within 3 business days. If they
    25    can't, please leave a comment and let the other person know that it will take
    26    longer. If life comes up, let others know that you need to unassign yourself
    27    and someone else will complete the review.
    28  
    29  # How to review a pull request
    30  
    31  1. Do not start reviewing a pull request if it is in WIP or is a draft pull
    32     request. Wait until they have marked it ready for review.
    33  1. Assign yourself to the pull request. This gives the author feedback that
    34     someone is going to do the review, while giving you time to do the review.
    35  1. Do a quick check for areas that need to be addressed before the pull request
    36     can be reviewed.
    37     
    38     For example, it is missing an agreed upon solution, requires an explanation
    39     from the author, has a very large set of changes that are not easy to review,
    40     etc., ask the author to correct that up-front.
    41  1. When you provide feedback, make it clear if the change must be made
    42     for the pull request to be approved, or if it is just a suggestion. Mark
    43     suggestions with **nit**, for example, `nit: I prefer that the bikeshed be
    44     blue`.
    45  1. When the pull request is ready to merge, squash the commits they require
    46     tidying unless the author asked to do that themselves.
    47  
    48  See [The life of a pull request](CONTRIBUTING.md#the-life-of-a-pull-request) for 
    49  what we expect a pull request to feel like for everyone involved.
    50  
    51  ## Merge Requirements
    52  
    53  * Unit Tests
    54  * Documentation Updated
    55  * Passing CI
    56  
    57  When a pull request impacts code, i.e. it's not a documentation-only change,
    58  the reviewer should run the manual integration tests after reviewing the code.
    59  The tests are triggered with a comment:
    60  
    61  ```
    62  /azp run porter-integration
    63  ```
    64  
    65  [Admins][admins] are allowed, at their discretion, to merge administrative pull
    66  requests without review and before the full CI suite has passed. This is
    67  sometimes used for typo fixes, updates to markdown files, etc. This is a
    68  judgement call based on the type of change, risk, and availability of other
    69  reviewers.
    70  
    71  ## Giving feedback
    72  
    73  * Be kind. Here is [good article][kind-reviews] with example code reviews and 
    74    how to improve your feedback. Giving feedback of this caliber is a requirement 
    75    of maintainers and those who cannot do so will have the maintainer role revoked.
    76  * Request changes for bugs and program correctness.
    77  * Request changes to be consistent with existing precedent in the codebase.
    78  * Request tests and documentation in the same pull request.
    79  * Prefer to optimize for performance when necessary but not up-front without
    80    a reason.
    81  * Prefer [follow-on PRs](CONTRIBUTING.md#follow-on-pr).
    82  * Do not ask the author to write in your style.
    83  
    84  [kind-reviews]: https://product.voxmedia.com/2018/8/21/17549400/kindness-and-code-reviews-improving-the-way-we-give-feedback
    85  
    86  # Cut a Release
    87  
    88  🧀💨
    89  
    90  Our CI system watches for tags, and when a tag is pushed, cuts a release
    91  of Porter. When you are asked to cut a new release, here is the process:
    92  
    93  1. Figure out the correct version number using our [version strategy].
    94      * Bump the major segment if there are any breaking changes, and the 
    95        version is greater than v1.0.0
    96      * Bump the minor segment if there are new features only.
    97      * Bump the patch segment if there are bug fixes only.
    98      * Bump the pre-release number (version-prerelease.NUMBER) if this is
    99        a pre-release, e.g. alpha/beta/rc.
   100  1. First, ensure that the main CI build has already passed for 
   101      the [commit that you want to tag][commits], and has published the canary binaries. 
   102      
   103      Then create the tag and push it:
   104  
   105      ```
   106      git checkout main
   107      git pull
   108      git tag VERSION -a -m ""
   109      git push --tags
   110      ```
   111      If the CI build failed to build for the release, fix the problem first. Then increment the PATCH version, e.g. v0.7.0->v0.7.1, and go through the above steps again to publish the binaries. It's often a good practice to finish the release first before updating any of our docs that references the latest release.
   112  
   113  1. Generate some release notes and put them into the release on GitHub.
   114     - Go to Porter Github repository and find the newly created release tag. You should see a
   115     "auto generate release notes" button to create release notes for the release.
   116     - Modify the generated release note to call out any breaking or notable changes in the release.
   117     - Include instructions for installing or upgrading to the new release:
   118      ```
   119        # Install or Upgrade
   120        Run (or re-run) the installation from https://porter.sh/install to get the
   121      latest version of porter.
   122      ```
   123  1. Announce the new release in the community.
   124     - Email the [mailing list](https://porter.sh/mailing-list) to announce the release. In your email, call out any breaking or notable changes.
   125     - Post a message in [Porter's slack channel](https://porter.sh/community/#slack).
   126  1. If there are any issues fixed in the release and someone is waiting for the fix, comment on the issue to let them know and link to the release.
   127  1. If the release contains new features, it should be announced through a [blog](https://porter.sh/blog/) post and on Porter's twitter account.
   128  
   129  [maintainers]: https://github.com/orgs/getporter/teams/maintainers
   130  [admins]: https://github.com/orgs/getporter/teams/admins
   131  [commits]: https://github.com/getporter/porter/commits/main
   132  [version strategy]: https://porter.sh/project/version-strategy/