Improve maintainer documentation

[basil]

Some topics that are of interest in onboarding new maintainers. @alecharp I can help edit or even write some of these sections if desired.

Debugging

Give an example of an error message that indicates a plugin should be pinned on an older line, and show how to pin it on an older line—everything from copying the older dependency to the older line's POM, sorting the resulting list with mvn spotless:apply, and dealing with properties (by copying the property to the older line's POM and also copying anything which references the property).

Document the process of bisecting a test failure to the breaking change. This should cover some common cases requiring two-level bisection, like a change in core causing a test failure in plugin A, or a change in plugin A causing a test failure in plugin B. These bisections aren't complicated in theory, but they can be complicated in practice because bisection across repositories is simplest when you can create a minimal reproducible example (MRE) outside of BOM (hence the next topic below).

As part of the above, show how to create a minimal reproducible example (MRE) of a test failure outside of BOM, in the repository of a particular plugin that is a part of BOM. Typically this involves a few steps: bringing the plugin's core baseline and BOM version up to the latest versions, then identifying any plugins of interest and adding them to test scope (if missing) in order to reproduce the compatibility failure.

Regression process

Document the process for backing out a regression and notifying the right people: reverting the change, disabling future Dependabot updates from reintroducing the regression, creating a minimal reproducible example, and notifying the author that a regression has occurred. In particular, we should always keep trunk passing at all times (rolling forward or otherwise reverting as quickly as possible), and we should never reject an upstream change without at least notifying upstream. Where practical and where the fix is obvious, we may also want to contribute a fix upstream, but this shouldn't be required in all cases. This documentation should lean on the documentation in the preceding section for bisecting changes and for creating minimal reproducible examples.

Document the process for adding a temporary workaround; namely, filing three issues/PRs:

• Issue/PR in BOM for adding the workaround (typically an exclusion in excludes.txt)
• Upstream issue for fixing the root cause of the problem
• Issue in BOM for removing the workaround once the root cause is fixed (typically removing the exclusion in excludes.txt)

All three issues/PRs are necessary for a successful long-term resolution.

Known issues

Explain how to recognize jenkinsci/maven-hpi-plugin#391 whose failure mode is particularly opaque and how we traditionally work around the problem (by adding the optional plugin to test scope in the consumer). The workaround is not very satisfying and sometimes maintainers resist the workaround. Explain how to counter this resistance by suggesting the resister either fix jenkinsci/maven-hpi-plugin#391 themselves or accept the ugly workaround.

Release process

Document the process for cutting a release: creating a release issue, locking the branch, getting a passing build, executing the release GitHub Action, closing the release issue, etc.