Introduce format version v2 by jsoriano · Pull Request #380 · elastic/package-spec

jsoriano · 2022-07-25T18:25:29Z

What does this PR do?

Initialize a new format version v2 as a copy of current v1 code. Semantic rules are instantiated from a new set of builders, one per major.

If/when this PR is merged, changes should be done in v2, and copied to v1 when non breaking.

Why is it important?

Allow to introduce breaking changes in a more controlled way.

Checklist

I have added test packages to test/packages that prove my change is effective.
I have added an entry in versions/N/changelog.yml.

Related issues

Closes Introduce new package spec version #345.

jsoriano · 2022-07-25T18:28:51Z

@@ -1,4 +1,4 @@
-format_version: 1.0.4
+format_version: 2.0.0


@elastic/ecosystem what should we do with test packages? I see some options:

Leave them as they are, update or add packages only to test new features in new versions.

Upgrade all of them to v2, copy good to goodv1 and leave this one as reference for v1.

Duplicate all packages, leaving v1 packages to test backwards compatibility.

It depends on the approach we choose - copy all spec files or leave them as is.

Leave them as they are, update or add packages only to test new features in new versions.

I would be for this option. We definitely don't need more copied files here :)

I would go also for the option 1, to avoid having more folders/files copied.

I was wondering about the test packages whose goal is to test errors. Should they be updated/copied to test those errors in both formats v1 and v2 ?

jsoriano · 2022-07-25T18:29:53Z

+  changes:
+  - description: Add definition for the license file in a package
+    type: enhancement
+    link: https://github.com/elastic/package-spec/pull/367


We should probably release all pending changes before merging this.

elasticmachine · 2022-07-25T18:32:58Z

💚 Build Succeeded

the below badges are clickable and redirect to their specific view in the CI or DOCS

Expand to view the summary

Build stats

Start Time: 2022-08-15T08:49:43.887+0000
Duration: 7 min 47 sec

Test stats 🧪

Test	Results
Failed	0
Passed	363
Skipped	2
Total	365

🤖 GitHub comments

To re-run your PR in the CI, just comment with:

/test : Re-trigger the build.

jsoriano · 2022-07-25T18:39:24Z

+## This file documents changes in the package specification. It is NOT a package specification file.
+## Newer entries go at the bottom.
+##
+- version: 2.0.0-next


Current approach keeps both majors in the same branch. This implies that releasing a minor for one major would require the release of new versions for all majors with changes. Releasing a new version will require to close all changelogs with changes, and push tags for all new versions mentioned in changelogs.

This makes me wonder a couple of things:

AFAIK we are not using minors for anything, should we do something about this? Or should we reduce versioning to only majors?
If we implement minors we could have more control on what is released for each major, but following current approach we would need to duplicate the spec and rules for each minor.

Should we have one branch per major? This would complicate other things, we would need an entry point for NewSpec, that instantiates one spec per major from a different import path.

With reducing versioning I mean to use format_version: 2 in manifests. We would keep the versioning here in changelogs.

Is there an option to keep it simple and forget about branches? This is a spec repository, we don't expect too many bugfixes :)

We can completely freeze version 1 when 2 is released, but I would expect a period where version 2 is in development, there are several potentially breaking changes that will need some time to be implemented. At least during this time we are going to need some kind of synchronization between both versions.

elasticmachine · 2022-07-25T19:11:54Z

🌐 Coverage report

Name	Metrics % (`covered/total`)	Diff
Packages	100.0% (`6/6`)	💚
Files	69.565% (`16/23`)	❕
Classes	75.0% (`24/32`)	❕
Methods	57.292% (`55/96`)	❕
Lines	41.681% (`471/1130`)	❕
Conditionals	100.0% (`0/0`)	💚

mtojek

Initialize a new format version v2 as a copy of current v1 code. Semantic rules are instantiated from a new set of builders, one per major.

I reviewed a similar project, compose-go, to see how they process incoming changes. It looks like the owners manage only one spec file instead of many spec-per-version files.

I'm wondering if we can try a similar approach, and mark properties/features in spec as deprecated in X version, removed in Y version.

WDYT?

mtojek · 2022-07-26T07:00:45Z

+## This file documents changes in the package specification. It is NOT a package specification file.
+## Newer entries go at the bottom.
+##
+- version: 2.0.0-next


Is there an option to keep it simple and forget about branches? This is a spec repository, we don't expect too many bugfixes :)

mtojek · 2022-07-26T07:03:01Z

@@ -1,4 +1,4 @@
-format_version: 1.0.4
+format_version: 2.0.0


It depends on the approach we choose - copy all spec files or leave them as is.

Leave them as they are, update or add packages only to test new features in new versions.

I would be for this option. We definitely don't need more copied files here :)

jsoriano · 2022-07-26T12:37:15Z

I reviewed a similar project, compose-go, to see how they process incoming changes. It looks like the owners manage only one spec file instead of many spec-per-version files.

Interestingly they are ignoring version, does it mean that they follow a strong backwards compatibility path?

Did you find anything like support for multiple versions there?

I'm wondering if we can try a similar approach, and mark properties/features in spec as deprecated in X version, removed in Y version.

We would also need something line "added in X version", and not sure how would this play with additionalContents depending on the version.

mtojek · 2022-07-26T13:26:04Z

I guess that we can review their history :)

compose-spec/compose-spec#12
compose-spec/compose-spec#123

jsoriano · 2022-07-28T11:43:41Z

I guess that we can review their history :)

compose-spec/compose-spec#12 compose-spec/compose-spec#123

After some analysis it seems that compose v2 doesn't use versioning, so they can keep a single spec file.

On #384 I follow a mixed approach, also with a single spec, but with rules that can be applied depending on the format_version.

jsoriano · 2022-08-23T10:21:46Z

Closing in favor of #384.

Introduce format version v2

2fdc5b4

jsoriano self-assigned this Jul 25, 2022

jsoriano commented Jul 25, 2022

View reviewed changes

Add missing files

3097b4f

mtojek reviewed Jul 26, 2022

View reviewed changes

jsoriano mentioned this pull request Jul 28, 2022

Introduce initial version 2 and stronger versioning support for the spec #384

Merged

2 tasks

This was referenced Aug 8, 2022

Introduce new package spec version #345

Closed

Refactor validator to separate spec loading code #388

Merged

Merge remote-tracking branch 'origin/main' into format-version

f043d56

jsoriano mentioned this pull request Aug 15, 2022

Use CUE to define schema for files #391

Closed

4 tasks

jsoriano closed this Aug 23, 2022

Conversation

jsoriano commented Jul 25, 2022

What does this PR do?

Why is it important?

Checklist

Related issues

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elasticmachine commented Jul 25, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

💚 Build Succeeded

Build stats

Test stats 🧪

🤖 GitHub comments

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elasticmachine commented Jul 25, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🌐 Coverage report

Uh oh!

mtojek left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jsoriano commented Jul 26, 2022

Uh oh!

mtojek commented Jul 26, 2022

Uh oh!

jsoriano commented Jul 28, 2022

Uh oh!

jsoriano commented Aug 23, 2022

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

elasticmachine commented Jul 25, 2022 •

edited

Loading

elasticmachine commented Jul 25, 2022 •

edited

Loading