Automatically replace version references on release:prepare

[Marcono1234]

When running mvn release:prepare automatically updates the version references in README.md and UserGuide.md, and also replaces $next-version$ with the new version. This is mainly useful for Javadoc (e.g. @since $next-version$) because it is not known in advance in which version a feature will be integrated.

The current solution seems to work (have tested it locally), but it is rather hacky and might rely on some implementation details / quirks of Maven and the Maven Release Plugin. So no worries if you don't want to integrate this. There might be better ways to solve this; any feedback is appreciated.

It appears Guava has a special @since NEXT and also automatically adds missing @since on release, but I was unable to find where exactly this is configured. Possibly it is using javadoc:fix, but I was not successful with applying this for Gson.

[Marcono1234]

This was a copy & paste error I made in #1700.

[Marcono1234]

Have removed this because it looks like this would prevent subsequent (non-dry-run) mvn release:prepare from working properly (unless you made a rollback in between)?

[eamonnmcmanus]

OK, I think I should be ready to give this a spin shortly.

[Marcono1234]

Thanks! The disadvantage of this manual approach seem to be that the rollback does not revert the additionally committed files (see 7bca5c4). But luckily that did not matter here. Another thing to look out for is that it runs git add ., so it would always be good to verify that no unrelated files were committed accidentally (was not a problem for this release either).

Also, do you happen to know how Guava does this? (quoting from the description)

It appears Guava has a special @since NEXT and also automatically adds missing @since on release, but I was unable to find where exactly this is configured. Possibly it is using javadoc:fix, but I was not successful with applying this for Gson.

[Marcono1234]

One disadvantage might also be that mvn release:prepare directly pushes the changes, and there seems to be no easy way to prevent this / defer this until having reviewed the changes locally. When using <pushChanges>false</pushChanges> it looks like you would have to manually push the commits and tag.

[eamonnmcmanus]

It appears Guava has a special @SInCE NEXT and also automatically adds missing @SInCE on release, but I was unable to find where exactly this is configured.

Both Gson and Guava are mirrored between GitHub and Piper, Google's internal monorepo. But the mirroring is different: for Gson we copy from GitHub to Piper while for Guava we copy from Piper to GitHub. Before making a Guava release, we use a shell script to update the @since tags in Piper, and those changes then get copied to GitHub. The process of adding @since NEXT tags in the first place is somewhat manual at the moment. All that to say that I don't think there's useful precedent there.