[FOLIO-1415] SPIKE: consider pre-release syntax for UI module snapshots Created: 16/Aug/18  Updated: 08/Feb/21

Status: Open
Project: FOLIO
Components: None
Affects versions: None
Fix versions: None

Type: Task Priority: P3
Reporter: Matthew Jones Assignee: Unassigned
Resolution: Unresolved Votes: 0
Labels: RFC, build-release, ci, platform-backlog
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original estimate: Not Specified

Issue links:
Relates
relates to STCOM-334 SPIKE: Propose a component/prop Depre... Closed
relates to FOLIO-1450 Revise FOLIO release and deployment p... Open
relates to FOLIO-1704 Expose next-major features/migration ... Open
relates to FOLIO-1344 use stripes-cli in the build and test... Closed
Sprint: CP: ready for planning
Story Points: 5
Development Team: Core: Platform

 Description   

This ticket is being creating because I don't want John Malconian's suggestion in FOLIO-1344 Closed get get overlooked:

I'm thinking that the way we version UI components in the CI needs to change. It doesn't make any sense to version a component in testing as v1.2.3000123 and then release v1.3.0. It would make more sense for a developer to version the component in Github as something like 1.3.0-SNAPSHOT before development for that sprint or feature branch begins - similar to the process the backend Maven developers use - The CI can then iteratively append build numbers to that i.e 1.3.0-SNAPSHOT.1 until the release is actually made for 1.3.0 or whatever. I know that there are some limitations to how NPM dependency resolution occurs with snapshot releases, but they may work in our favor with this model - TBD.

Use of this pre-release syntax will also enable our build numbers to adhere to semver. Currently our npm-folioci build numbers can be misleading at the patch segment. For example, version 1.2.3000123 generated from a package defining itself as 1.2.3, technically can be satisfied by a request for ^1.2.4. Also, determining compatibility with our own npm-folio can also be a challenge. For example, is 1.2.3000456 actually the CI build of 1.2.3 or a build working toward 1.3.0?

One challenge, as I understand from the earlier JIRAs on this topic ( FOLIO-690 Closed and FOLIO-696 Closed ), is with pulling in the latest versions of stripes dependencies defined below the platform's package.json (eg. platform > ui-app > stripes-smart-components > stripes-components). Grouping our stripes-* dependencies ( STRIPES-543 Closed ) should alleviate this, by pointing the app/platform to a version/snapshot of the framework which takes care of the underlying dependencies.



 Comments   
Comment by Matthew Jones [ 16/Aug/18 ]

To make this work, what would the process look like? Here is one suggestion:

Step Example
Typical development in the master branch maintains a package.json matching x.y.z-SNAPSHOT, where "x.y.z" represents one patch number increment over the prior release 1.2.4-SNAPSHOT when prior release was 1.2.3
Changelog.md reflects progress toward version x.y.z 1.2.4 (IN PROGRESS)
As merges into master are made, Jenkins/CI publishes packages as x.y.z.-SNAPSHOT.buildnumber to npm-folioci 1.2.4-SNAPSHOT.107 (npm-folioci)
When creating a release branch, developer follows typical release process reconciling changelog as necessary. New: The developer omits "-SNAPSHOT" from the package.json 1.2.4
A merge without "-SNAPSHOT" instructs Jenkins to publish version x.y.z to npm-folio, in addition to npm-folioci. Tagged automatically. 1.2.4 (npm-folio) and 1.2.4.SNAPSHOT.108 (npm-folioci)
Then package.json version is automatically bumped by a patch number and -SNAPSHOT is appended back to the package.json in preparation for more work 1.2.5-SNAPSHOT
At any point during subsequent development, should a new feature be added (rather than fix), the minor version is bumped. 1.3.0-SNAPSHOT
Likewise, should a breaking change be introduced the major version is bumped. In either case "-SNAPSHOT" remains. 2.0.0-SNAPSHOT

Note:
This suggestion maintains the pre-release suffix (SNAPSHOT) in the master branch, using the omission of the suffix as a trigger to publish to npm-folio. This could be reversed, however, where CI automatically appends "-SNAPSHOT" on non-release merges, using another trigger (the tag?) to prompt CI to publish to npm-folio. That said, having "-SNAPSHOT" exist in master may give clarity to the fact that a developer cloning master is working on unreleased code, particularly when developing in a workspace environment that has a lot of modules in play.

Comment by Matthew Jones [ 16/Aug/18 ]

What does this look like when building a platform in CI?

Because of the pre-release suffix, we won't be able to use "latest" or ">=0.0.0" for dependencies (the latter of which basically says "I'll take any version"). We will have to be more specific in knowing the latest intended major.minor.patch, but could take the latest snapshot:

"dependencies": {
    "@folio/users": ">2.12.3-SNAPSHOT",
    "@folio/stripes": ">1.0.0-SNAPSHOT"
},
Generated at Thu Feb 08 23:13:10 UTC 2024 using Jira 1001.0.0-SNAPSHOT#100246-sha1:7a5c50119eb0633d306e14180817ddef5e80c75d.