docs: use GH base sha to lint PR commits

[robjweiss]

Description

The current documentation suggests using HEAD~n to go through all PR commits where n is the number of commits in the PR. This may not always produce the desired result though, especially if the history is not perfectly linear and there is a complex history of merges.

GitHub Actions provides the base sha on the pull_request object as well. This should give a revision list in line with the git log and revisions shown on GitHub.

Motivation and Context

While using the previous CI workflow, I found that the commits being linted where different from those I was seeing in the PR. After reading a bit about how ~ and ^ work with git I came to the conclusion that going ~n will not necessarily point to the same revision as the first commit shown in the PR (merge base), especially if the history is complex.

These are my findings. If there's something I've overlooked or you think my conclusions are incorrect, please do let me know!

The original discussion on the GitHub docs seems to come from here: #586.

Usage examples

In a GitHub Action:

npx commitlint --from ${{ github.event.pull_request.base.sha }} --to ${{ github.event.pull_request.head.sha }} --verbose

How Has This Been Tested?

I compared the commits linted by using each method. The commits linted by the existing method included some not shown in the PR. The commits linted by the new method matched exactly.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Chore (documentation)

Checklist:

• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my changes.
• All new and existing tests passed.

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

[escapedcat]

Hey @robjweiss , thanks for this. Would you mind removing the scope from your commit message? It's not a valid scope for this project.

@knocte wdyt?

[robjweiss]

@escapedcat no problem, updated.