docs: Suggest using the new Github option for consistent commit titles

README.md

@@ -1,8 +1,8 @@
 # action-semantic-pull-request
 
-This is a [GitHub Action](https://github.com/features/actions) that ensures that your PR title matches the [Conventional Commits spec](https://www.conventionalcommits.org/).
+This is a [GitHub Action](https://github.com/features/actions) that ensures your PR title matches the [Conventional Commits spec](https://www.conventionalcommits.org/).
 
-This is helpful when you're using [semantic-release](https://github.com/semantic-release/semantic-release) with the Conventional Commits preset. When using the "Squash and merge" strategy, GitHub will suggest to use the PR title as the commit message. With this action you can validate that the PR title will lead to a correct commit message and subsequently the expected release.
+The typical use case is to use this in combination with a tool like [semantic-release](https://github.com/semantic-release/semantic-release) to automate releases.
 
 ## Validation
 
@@ -16,8 +16,10 @@ Note that since PR titles only have a single line, you have to use the `!` synta
 
 See [Conventional Commits](https://www.conventionalcommits.org/) for more examples.
 
-## Example config
+## Installation
 
+1. If your goal is to create squashed commits that will be used for automated releases, you'll want to configure your GitHub repository to [use the squash & merge strategy](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/configuring-commit-squashing-for-pull-requests) and tick the option "Default to PR title for squash merge commits".
+2. [Add the action](https://docs.github.com/en/actions/quickstart) with the following configuration
 ```yml
 name: "Lint PR"
 
@@ -42,6 +44,16 @@ jobs:
 
 The action works without configuration, however you can provide options for customization.
 
+The following terminology helps to understand the configuration options:
+
+```
+feat(ui): Add `Button` component.
+^    ^    ^
+|    |    |__ Subject
+|    |_______ Scope
+|____________ Type
+```
+
 ```yml
         with:
           # Configure which types are allowed.
@@ -55,8 +67,8 @@ The action works without configuration, however you can provide options for cust
             ui
           # Configure that a scope must always be provided.
           requireScope: true
-          # Configure which scopes are disallowed in PR titles. For instance,  by setting
-          # the value below, `chore(release): ...` or `ci(e2e,release): ...` will be rejected.
+          # Configure which scopes are disallowed in PR titles. For instance by setting
+          # the value below, `chore(release): ...` and `ci(e2e,release): ...` will be rejected.
           disallowScopes: |
             release
           # Configure additional validation for the subject based on a regex.
@@ -69,14 +81,6 @@ The action works without configuration, however you can provide options for cust
             The subject "{subject}" found in the pull request title "{title}"
             didn't match the configured pattern. Please ensure that the subject
             doesn't start with an uppercase character.
-          # When using "Squash and merge" on a PR with only one commit, GitHub
-          # will suggest using that commit message instead of the PR title for the
-          # merge commit, and it's easy to commit this by mistake. Enable this option
-          # to also validate the commit message for one commit PRs.
-          validateSingleCommit: true
-          # Related to `validateSingleCommit` you can opt-in to validate that the PR
-          # title matches a single commit to avoid confusion.
-          validateSingleCommitMatchesPrTitle: true
           # If you use GitHub Enterprise, you can set this to the URL of your server
           githubBaseUrl: https://github.myorg.com/api/v3
           # If the PR contains one of these labels, the validation is skipped.
@@ -108,3 +112,16 @@ There are two events that can be used as triggers for this action, each with dif
 
 1. [`pull_request_target`](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#pull_request_target): This allows the action to be used in a fork-based workflow, where e.g. you want to accept pull requests in a public repository. In this case, the configuration from the main branch of your repository will be used for the check. This means that you need to have this configuration in the main branch for the action to run at all (e.g. it won't run within a PR that adds the action initially). Also if you change the configuration in a PR, the changes will not be reflected for the current PR – only subsequent ones after the changes are in the main branch.
 2. [`pull_request`](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#pull_request): This configuration uses the latest configuration that is available in the current branch. It will only work if the branch is based in the repository itself. If this configuration is used and a pull request from a fork is opened, you'll encounter an error as the GitHub token environment parameter is not available. This option is viable if all contributors have write access to the repository.
+
+## Legacy configuration
+
+When using "Squash and merge" on a PR with only one commit, GitHub will suggest using that commit message instead of the PR title for the merge commit and it's easy to commit this by mistake. To help out in this situation this action supports two configuration options. However, [GitHub has introduced an option to streamline this behaviour](https://github.blog/changelog/2022-05-11-default-to-pr-titles-for-squash-merge-commit-messages/), so using that instead should be preferred.
+
+```yml
+          # If the PR only contains a single commit, the action will validate that
+          # it matches the configured pattern.
+          validateSingleCommit: true
+          # Related to `validateSingleCommit` you can opt-in to validate that the PR
+          # title matches a single commit to avoid confusion.
+          validateSingleCommitMatchesPrTitle: true
+```