Ship/Show/Ask

Ship/Show/Ask is a fairly recent strategy to improve the workflow of your Pull Requests.

Its goal is to provide the advantages of having pull requests, while at the same time keeping a fast pace in producing new features. It does it by partitioning your pull requests into three categories : Ship, Show and Ask.

This strategy differs from more classical PR workflows by automating the management of trivial or small pull requests. This, in turn, gives more room to carefully handle complex changes in more interesting pull requests.

The app will help you apply the Ship/Show/Ask workflow to your pull requests, by guiding you through the decision to chose any of the three categories.

What is Ship?

You will use Ship pull requests when you make small, barely noticeable changes that don’t require people to review, nor even to be aware of. Such small changes could in theory be pushed directly to the target branch, but for external reasons (e.g., internal policy, CI pipeline), you still want to keep it as a record pull request.

Examples:

• Fixing a typo or spelling mistake

• Increasing a dependency’s minor version

• A bugfix you already discussed with the team or paired programmed on

What is Show?

Choose Show pull request when you want to show what has been done, but otherwise you would like it to be merged automatically. You still want people to be notified of the change (for example so that they can review later on) but you don’t expect the need for deep discussions.

Examples:

• Completing a well defined issue/ticket

• a local refactoring you want people to be aware of (e.g., renaming a function or changing a small implementation detail)

• added test cases

What is Ask?

You will typically opt in for an Ask pull request when you want feedback and discussions on the changes you made. You only want to merge these changes after there was enough time for discussion, reviewing changes, and decide that it is fully ready. Ask pull requests correspond to the classical way of working with pull requests.

Examples:

• Adding a new feature

• Changing how a feature work

• Major refactoring

See also Rouan Wilsenach’s “Ship/Show/Ask” article on Martin Fowler’s homepage.

How does it work?

All pull requests are characterized by the app by 5 different categories. The behaviour of these categories is summarized in the table below.

Note that when you are not using full Ship/Show/Ask support, the Auto merge [Auto] behaviour is equivalent to [Show], except that it does not skip the Code Owners merge checks.

Ask pull requests

When an [Ask>=n] pull request is initiated, it will not be merged automatically. Moreover, a merge check requiring n (>=1) approvals is added to the pull request. This means that in order for the pull request to be successfully merged, it must receive n approvals from designated reviewers or team members.

This type of pull request is useful when changes to the codebase have the potential to have a significant impact or when there is a high level of uncertainty surrounding a particular change.

To initiate an [Ask>=n] pull request, the user must select Manual merge and ask to require a certain number of approvals via the dedicated drop-down.

Show pull requests

You can configure Pull Requests to be merged automatically, optionally requiring a certain number of approvals.

[Show>=n] pull requests will be automatically merged as soon as they receive n approvals. However, Code Owners merge checks will be ignored for such pull request. All other merge checks (such as passing tests, no open tasks, etc.) must still be fulfilled for the pull request to be merged.

[Show] pull requests, on the other hand, will not require any approvals before they can be automatically merged. This feature is useful for small changes that do not require a thorough review. Again, Code Owners merge checks will be ignored but all other merge checks must still be fulfilled before the pull request can be merged.

To initiate a [Show] pull request, the user must select Auto-Merge and don’t require any approvals. To initiate a [Show>=n] pull request, the user must select Auto-Merge and must require a certain number of approvals.

Ship pull requests

[Ship] pull requests are similar to [Show] pull requests, with the difference that they do not add the Code Owners as reviewers anymore. That means that no one will be notified about the pull request. You can still add reviewers manually if desired.

Like [Show] pull requests, [Ship] pull requests will be merged as soon as all other merge checks pass, but they skip Code Owners assignments from Code Owners.

To initiate a [Ship] pull request, the user must select Auto-Merge, they should not require any approvals and they must select Merge without reviewers.