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

Introduced "latest" xsd file path #2886

Merged
merged 1 commit into from Jun 6, 2022
Merged

Introduced "latest" xsd file path #2886

merged 1 commit into from Jun 6, 2022

Conversation

nvoxland
Copy link
Contributor

Description

Main Change

We ship a new xsd version with each non-patch release of liquibase, but while some people find that helpful others find it overly complex. Furthermore, examples and documentation gets difficult to keep up to date when references need to be constantly updated.

This PR would solve that problem by introducing a new dbchangelog-latest.xsd url so people can use:

<databaseChangeLog
        xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:pro="http://www.liquibase.org/xml/ns/pro"
        xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd
    http://www.liquibase.org/xml/ns/pro http://www.liquibase.org/xml/ns/pro/liquibase-pro-latest.xsd ">

as an XSD reference if they don't want to be locked into the specific version.

With each new non-patch release, we:

  1. Copy the new versioned xsd over the old dbchangelog-latest.xsd file
  2. Upload the new dbchangelog-latest.xsd file to the site

Because Liquibase reads the dbchangelog XSD files from the shipped jar, "latest" will always be the version shipped in the version of liquibase they run.

BUT: that may be different than the version currently at http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd if they are not on the actual latest version of Liquibase.

AND ALSO BUT: other tools like IDEs rely on downloading the xsd and caching it, so that may become out of sync in surprising ways

Secondary changes

  • I updated the quick-start examples to use the -latest.xsd so they don't get out of date, and are following the "easy" best practice
  • I updated the header generated in generate-changelog to use -latest.xsd to follow the "easy" best practice
  • While I was in the code, I updated the "get schema version" method to return "next" for development builds and compute the version for production builds to avoid drift

Things to Worry About

I think PR makes sense if the following "best practice" is actually what we want to suggest:

  1. When people start using Liquibase, they should use dbchangelog-latest.xsd.
    a. Therefore our docs should always use -latest.xsd with one new page added explaining the pros and cons to using -latest vs a versioned xsd.
  2. IF they hit a case where they find that doesn't work for them, they can change their references to the versioned file.
    a. The primary driver for this would be people who rely on external tools like an IDE that caches too hard and/or is too "ahead" of the version of liquibase they use.

My theory is that the XSD tends to change infrequently enough and when it does it is just in minor ways that even if IDEs etc are using an older or newer version most differences won't get noticed. But maybe those small differences will be annoying and surprising enough that it overwhelms the "nice to have" of not longer having to think about the version info in the file.

But is that a valid theory?

- Updated examples to use latest.xsd filese
- Removed unused getLocalPath() function from NamespaceDetails
@nvoxland nvoxland requested review from suryaaki2 and removed request for suryaaki2 May 26, 2022 22:09
@nvoxland nvoxland added this to To Do in Conditioning++ via automation May 26, 2022
@github-actions
Copy link

Unit Test Results

  4 512 files  ±  0    4 512 suites  ±0   31m 7s ⏱️ - 1m 22s
  4 426 tests +  7    4 208 ✔️ +  7     218 💤 ±0  0 ±0 
52 392 runs  +84  47 380 ✔️ +84  5 012 💤 ±0  0 ±0 

Results for commit 8e6c187. ± Comparison against base commit 4ab687b.

@nvoxland nvoxland requested a review from suryaaki2 May 27, 2022 21:04
@FBurguer FBurguer self-assigned this Jun 6, 2022
@FBurguer
Copy link

FBurguer commented Jun 6, 2022

The example dir has been updated to have http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd and
http://www.liquibase.org/xml/ns/pro http://www.liquibase.org/xml/ns/pro/liquibase-pro-latest.xsd also generate changelog generates a changelog with latest.xsd.

Test Environment:
OS:Windows 10
Java 11
H2 2.1.212

@kataggart kataggart added the XSD label Jun 6, 2022
@kataggart
Copy link
Contributor

@nvoxland @FBurguer please make sure docs are updated as well. Thanks!

@nvoxland nvoxland merged commit 6d1b853 into master Jun 6, 2022
Conditioning++ automation moved this from To Do to Done Jun 6, 2022
@nvoxland nvoxland deleted the introduce-latest-xsd branch June 6, 2022 19:06
@kataggart kataggart added this to the NEXT milestone Jun 7, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Archived in project
Development

Successfully merging this pull request may close these issues.

None yet

5 participants