Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Automatically replace version references on release:prepare #2212

Conversation

Marcono1234
Copy link
Collaborator

@Marcono1234 Marcono1234 commented Oct 1, 2022

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 Marcono1234 force-pushed the marcono1234/automatically-replace-version-on-release branch from 5165808 to 30fabf4 Compare October 1, 2022 01:54
@Marcono1234 Marcono1234 changed the title Replace version references during release Automatically replace version references on release:prepare Oct 1, 2022
@Marcono1234 Marcono1234 force-pushed the marcono1234/automatically-replace-version-on-release branch from 30fabf4 to 24a1ed6 Compare October 1, 2022 01:58
@Marcono1234 Marcono1234 force-pushed the marcono1234/automatically-replace-version-on-release branch from 24a1ed6 to a86f142 Compare October 1, 2022 02:06
@@ -1299,10 +1302,10 @@ public <T> T fromJson(JsonElement json, Type typeOfT) throws JsonSyntaxException
* @return an object of type T from the JSON. Returns {@code null} if {@code json} is {@code null}
* or if {@code json} is empty.
* @throws JsonSyntaxException if json is not a valid representation for an object of type typeOfT
* @since 1.3
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@@ -6,7 +6,6 @@ The following is a step-by-step procedure for releasing a new version of Google-
1. Ensure all changelists are code-reviewed and have +1
1. `cd gson` to the parent directory; ensure there are no open files and all changes are committed.
1. Run `mvn release:clean`
1. Do a dry run: `mvn release:prepare -DdryRun=true`
Copy link
Collaborator Author

@Marcono1234 Marcono1234 Oct 1, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member

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

@eamonnmcmanus eamonnmcmanus merged commit 4f948dd into google:master Oct 25, 2022
@Marcono1234 Marcono1234 deleted the marcono1234/automatically-replace-version-on-release branch October 25, 2022 16:23
@Marcono1234
Copy link
Collaborator Author

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
Copy link
Collaborator Author

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
Copy link
Member

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants