w3id.org

Appearance

git/branch-not-stale ​

Severity: notice · Status: enforced · Applies to: repository-wide

What ​

A branch should start from a reasonably recent master.

Why ​

A fork that was cloned once and never updated diverges quietly. The change itself is usually still fine — identifier directories rarely conflict with each other — but three things go wrong:

  • the pull request is harder to review, because the diff is computed against a base nobody is looking at any more;
  • the contributor reaches for "Sync fork", which merges rather than rebases and drags a merge commit plus everything since into the pull request. See git/no-merge-commits;
  • the checks can miss things. The pull request's own checks run on the change merged into the current master, so they use the current rules however old the branch is — but GitHub runs no checks at all on a pull request with a merge conflict, and the checker you run yourself is whatever version your branch has.

This is a notice, not a warning. Being behind is not itself a mistake, and it never blocks anything — it is here because it is the step before the mistake.

Wrong ​

Nothing, exactly. This is advice.

sh
$ git fetch upstream
$ git rev-list --count HEAD..upstream/master
3

How to fix ​

From the command line:

sh
git fetch upstream
git branch backup-my-change   # a copy to go back to if this goes wrong
git rebase upstream/master
git push --force-with-lease   # a plain push is rejected; do not pull instead

Git's message for the rejected push suggests git pull. After a rebase, that either stops with an error or merges the old commits back in, adding the merge commit git/no-merge-commits reports. Delete the copy with git branch -D backup-my-change once the pull request is merged.

For a fork you have not touched in a long time, it is often quicker to start a new branch from upstream/master and re-apply your change, keeping the old branch until the new one is pushed.

In the browser:

  • Before you start a change, open your fork on GitHub and use Sync fork, then make your edit. If you have not committed to your fork's default branch, this only catches it up.
  • Once the pull request is open, use the Update branch button in the merge section near the bottom of the pull request, and choose Update with rebase from its dropdown. GitHub shows the button when there are no merge conflicts and the branch is behind. The plain Update branch and Update with merge commit add a merge commit, which git/no-merge-commits reports.

How to check ​

Run w3id-check with --rule git/branch-not-stale to check this rule on its own; without it the tool runs every rule, as the pull request checks do. This rule looks at your commits rather than your files, so it needs a base to compare against; narrowing it to a path would not change what it reports.

sh
node tools/check/bin/w3id-check.js --rule git/branch-not-stale

The threshold is configurable in .w3id-check.yaml under options.git/branch-not-stale.maxBehind.

Testing your changes covers installing the tool, and what else is worth checking by hand.

See also ​