Add support for configuring Liquibase's tag

[eddumelendez]

See gh-19200

[snicoll]

Thanks for the PR. While it technically does expose a property, I am not happy with the current documentation (and potentially how it is namespaced). I've added a question.

[snicoll]

While reviewing this PR, I was trying to improve the documentation of that property and couldn't really find my way in the liquibase documentation. The original issue states:

This property will help in generating roll back scripts for particular tags only when user has specified rollbackFile property.

Do you know more about this property and how it's actually used? I've looked into the liquibase source code and I am not sure I understood the scope of that property. If that's used only for rollbacks, I think we should make that clearer in the description of the property.

[eddumelendez]

when I was looking into the code I found SpringLiquibase uses tag property at performUpdate and generateRollbackFile methods. It means is executed during the update of changelogs or if additionally rollbackFile is also set will generate the file.

[snicoll]

Thanks for the feedback. Same but I think "Name of the tag" isn't enough for users to figure out what to do. Perhaps this is an issue in the Liquibase documentation?

[snicoll]

I poked around and I am confused. I don't think we should just have a "tag" property, I've commented on the original issue.

[eddumelendez]

sorry for the late reply Stéphane! I have been thinking about it and TBH I think the workflow is pretty much deploying changes using the CLI and generating the rollback file from the application. As we have seen, the same property is used for rolling out and rollback. Said that, we should be very careful about the docs as you are worried about.

Delivering this feature, people will be able to:

1. Use tag property, apply the tag value to the scripts

or

2. Use tag property and rollbackFile, generate the file to perform a rollback

[snicoll]

@SteveDonie thanks for the feedback and improving the docs.

We need a one sentence that would be a good summary for the property and we had a hard time finding something succinct.

Here is a proposal

Tag name to add to applied changes. Can be used with "rollbackFile" to generate a rollback script for all existing changes with that tag.

Thoughts?

[SteveDonie]

I think that is pretty good. Maybe even call out that there are two different uses:

Tag name to apply when applying database changes. Tag name to use as a target when rolling back already applied changes.

[SteveDonie]

When rolling back, you don't have to generate a rollbackFile. I'm not sure how it works in spring boot, but from the command line there are two commands - rollback, and rollbackSQL. One does the actual rollback, and the other generates the SQL to perform the rollback and shows it on the console (or sends it to a file).

[wilkinsona]

Thanks very much for the pointers, @SteveDonie.

[snicoll]

Indeed, thank you @SteveDonie. FTR, Spring Boot "merely" instruments SpringLiquibase which is part of Liquibase itself.