[jira] [Comment Edited] (MRELEASE-938) Need better support for staging release candidates with git and Nexus

["Christopher Tubbs (Jira)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/MRELEASE-938?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17001621#comment-17001621 ] 

Christopher Tubbs edited comment on MRELEASE-938 at 12/21/19 4:58 AM:
----------------------------------------------------------------------

[~elharo]  This can *not* be fixed by Nexus behavior changes, because:

1. Nexus should not have access to the project's git repository to alter the tags if moving from staged to release, and it certainly shouldn't have the GPG private keys to create signed tags, and
2. Nexus should not be modifying the pom.xml's scm section to update the tag name in the pom when moving from staged to release, especially since that would break the user's GPG signatures on those pom artifacts.

To be clear, although staging to Nexus is a driving use case, the relevant issues have little to nothing to do with Nexus. This is really about the git tag management limitations performed this plugin that could be improved.

To attempt to explain it more clearly:

* This plugin creates a git tag during {{prepare}} based on the {{<tagNameFormat/>}}.
* This plugin modifies the {{<tag/>}} element in the POM's {{<scm/>}} section according to the tag name format.
* When you are using the plugin to stage release candidates, you do *not* want it to create a git tag based on the final release when you don't yet know if the release candidate will be the final release (especially in ASF if the final release tag name looks like {{rel/project-version}}, because tags starting with {{rel}} are locked and can't be deleted without help from INFRA).

Your options are to:

1. skip tag creation and manually create a tag after the release candidate is decided to be released, or
2. create a tag name format that includes a release candidate sequence number, like {{rel/project-version-rc1}}.

The problem with option 1 is that this plugin doesn't have any such option to skip tag creation. You do have the option to skip the git push, but that is inconvenient, because it isn't the default and it also skips pushing the new commits in the branch that update the versions in the pom.xml files, and in any case... even if you skipped pushing, you'd still have a local tag that might unintentionally get pushed later.

The problem with option 2 is that the pom.xml file's {{scm}} section that this plugin updated will have the wrong tag name if the release candidate is approved for release (it will have the tag name ending in "-rc1" rather than the final tag name, making it more difficult for people with a copy of the release to be able to find the correct corresponding git tag for the release associated with a given pom.xml. This is particularly problematic for other tools like maven-site-plugin, which make use of the scm information in the pom to create links for users on a project's website that goes back to the tag.

This could be fixed by either of the following two solutions:

1. Add an option of this plugin to skip git tag creation, and expect users to do that manually later. This will cause problems with the {{perform}} goal's ability to check out the commit (because the tag won't exist), but {{HEAD~1}} could be used with {{localCheckout}}, so long as {{suppressCommitBeforeTag}} is not used. This solution would allow the plugin's modification to the scm section of the pom to work only once the user manually created their own tag of the same name, but they wouldn't have to worry about any automatically created tags made by this plugin that would interfere with that.

Or,

2. This plugin could be modified so that the name of the actual git tag branch could be specified separately from the final tag name that gets put into the pom's scm section. So, "project-version-rc1", "project-version-rc2", and "project-version-rc3" git tags could all be created by this plugin, all containing the same pom with the scm section showing a tag name that is simply "project-version". Then, a user can simply create a "project-version" tag from the same commit as whichever "project-version-rcX" tag was approved for final release (without having to recreate the staged artifacts in Nexus with a corrected pom.xml).

I know this is a bit obscure of a use case... so if I've explained it poorly, I apologize. If both proposed options are rejected, for whatever reason, that's fine. It's just a bit more work to do local git tag management in a build script outside of maven... I had just hoped that this release plugin could handle this (seemingly common) use case so we could encapsulate the entire release process within the configuration for this plugin.

Mostly, I just want to make sure the reason for rejecting the suggestion isn't based on misunderstanding the nature of the problem being described.


was (Author: ctubbsii):
[~elharo]  This can *not* be fixed by Nexus behavior changes, because:

1. Nexus should not have access to the project's git repository to alter the tags if moving from staged to release, and it certainly shouldn't have the GPG private keys to create signed tags, and
2. Nexus should not be modifying the pom.xml's scm section to update the tag name in the pom when moving from staged to release, especially since that would break the user's GPG signatures on those pom artifacts.

To be clear, although staging to Nexus is a driving use case, the relevant issues have little to nothing to do with Nexus. This is really about the git tag management limitations performed this plugin that could be improved.

To attempt to explain it more clearly:

* This plugin creates a git tag during {{prepare}} based on the {{<tagNameFormat/>}}.
* This plugin modifies the {{<tag/>}} element in the POM's {{<scm/>}} section according to the tag name format.
* When you are using the plugin to stage release candidates, you do *not* want it to create a git tag based on the final release when you don't yet know if the release candidate will be the final release (especially in ASF if the final release tag name looks like {{rel/project-version}}, because tags starting with {{rel}} are locked and can't be deleted without help from INFRA).

Your options are to:

1. skip tag creation and manually create a tag after the release candidate is decided to be released, or
2. create a tag name format that includes a release candidate sequence number, like {{rel/project-version-rc1}}.

The problem with option 1 is that this plugin doesn't have any such option to skip tag creation. You do have the option to skip the git push, but that is inconvenient, because it isn't the default and it also skips pushing the new commits in the branch that update the versions in the pom.xml files, and in any case... even if you skipped pushing, you'd still have a local tag that might unintentionally get pushed later.

The problem with option 2 is that the pom.xml file's {{scm}} section that this plugin updated will have the wrong tag name if the release candidate is approved for release (it will have the tag name ending in "-rc1" rather than the final tag name, making it more difficult for people with a copy of the release to be able to find the correct corresponding git tag for the release associated with a given pom.xml. This is particularly problematic for other tools like maven-site-plugin, which make use of the scm information in the pom to create links for users on a project's website that goes back to the tag.

This could be fixed by either of the following two solutions:

1. Add an option of this plugin to skip git tag creation, and expect users to do that manually later. This will cause problems with the {{perform}} goal's ability to check out the commit (because the tag won't exist), but {{HEAD~1}} could be used with {{localCheckout}}, so long as {{suppressCommitBeforeTag}} is not used. This solution would allow the plugin's modification to the scm section of the pom to work only once the user manually created their own tag of the same name, but they wouldn't have to worry about any automatically created tags made by this plugin that would interfere with that.

Or,

2. This plugin could be modified so that the name of the actual git tag branch could be specified separately from the final tag name that gets put into the pom's scm section. So, "project-version-rc1", "project-version-rc2", and "project-version-rc3" git tags could all be created by this plugin, all containing the same pom with the scm section showing a tag name that is simply "project-version". Then, a user can simply create a "project-version" tag from the same commit as whichever "project-version-rcX" tag was approved for final release (without having to recreate the staged artifacts in Nexus with a corrected pom.xml).

I know this is a bit obscure of a use case... so if I've explained it poorly, I apologize. If both proposed options are rejected, for whatever reason, that's fine. It's just a bit more work to do local git tag management in a build script outside of maven... I had just hoped that this release plugin could handle this (seemingly common) use case so we could encapsulate the entire release process within the configuration for this plugin.

> Need better support for staging release candidates with git and Nexus
> ---------------------------------------------------------------------
>
>                 Key: MRELEASE-938
>                 URL: https://issues.apache.org/jira/browse/MRELEASE-938
>             Project: Maven Release Plugin
>          Issue Type: Improvement
>            Reporter: Christopher Tubbs
>            Priority: Major
>
> Use case:
> An ASF project creates git tags which are GPG-signed named "rel/<version>" after a release is voted on. If the release passes, the contents of the pom.xml files should refer to this final tag, and not any intermediate release candidate tag name.
> To avoid pushing the release prior to building a release candidate and publishing it to the staging maven repository, the configuration sets {{<pushChanges>false</pushChanges>}} and {{<localCheckout>true</localCheckout>}}, and the tag name is created with {{<tagNameFormat>rel/@\{project.version\}</tagNameFormat>}}.
> There is still a risk of a release manager accidentally pushing the tag created by the maven-release-plugin, which has the final name, but is not GPG signed, and should not be pushed, because it cannot (and should not) change once it is.
> What might be useful here is an alternate, intermediate name, {{@\{project.version\}}} which can be used as the checkout tag for the perform step.
> Alternatively, no tag actually has to be created in this case (a GPG-signed tag is manually created later). Unless {{suppressCommitBeforeTag}} is set, the perform step can check out from {{HEAD~1}}, instead. An option to skip tag creation entirely could work under these circumstances.



--
This message was sent by Atlassian Jira
(v8.3.4#803005)