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.

Sign up for GitHub

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

Jump to bottom

Leaf: Clarify the prerelease-flag #75

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Leaf: Clarify the prerelease-flag #75

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
7f251eb
Leaf: Clarify the prerelease-flag
oej Nov 18, 2024
b516726
doc: grammar
madpah Nov 20, 2024
da01fdb
doc: grammar
madpah Nov 20, 2024
c7dcce0
doc: grammar / spelling
madpah Nov 20, 2024
c6897b0
doc: grammar / spelling
madpah Nov 20, 2024
c376f19
doc: grammar / spelling
madpah Nov 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 15 additions & 4 deletions tea-leaf/tea-leaf.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
_Work in progress_

The TEA LEAF is the object that indicates a product version. The API should be
very agnostic to how a "version" is indicated - semver, name, hash or anything else.
very agnostic to how a "version" is indicated - semver, vers, name, hash or anything else.
madpah marked this conversation as resolved.
Show resolved Hide resolved

## Major and minor versions

Expand All @@ -16,12 +16,23 @@ a timestamp for a release is required.

## The Leaf Object

- __UUID__ unique for this object
- __Uuid__ unique for this object
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We've called this an identifier (which is of type UUID) in the OpenAPI Spec - we need to align in either direction.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree

- __Product name__: A text field
- __Product version__: A text field, no required syntax
- __Release date__: A unix timestamp
- __Prerelease__: A flag indicating a pre-release (beta, rc)
- __TCO_UUID__: A reference to the TEA Collection objet for this release
- __Prerelease__: A boolean flag indicating a pre-release (beta, rc)
madpah marked this conversation as resolved.
Show resolved Hide resolved
- __Tco_uuid__: A reference to the TEA Collection objet for this release

## Handling the Prerelease flag
madpah marked this conversation as resolved.
Show resolved Hide resolved

The Prerelease flag is used to indicate that this is not a final release. For a given Leaf with a UUID, the flag
madpah marked this conversation as resolved.
Show resolved Hide resolved
can be set to indicate a "test", "beta", "alfa" or similar non-deployed release. It can only be set when
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we stress the fact that this applies to non-deployed releases, regardless of the naming.

For example org.apache.logging.log4j:log4j-core:3.0.0-beta3 does not count as pre-release, since we are not allowed by Maven Central to modify it.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would definitely set something named "-beta3" as a prerelease. If you modify something, that's always a new release with a new leaf. Maybe we need to be clearer in the text.

The thing with the flag change was that in some cases a pre-release is upgraded to final release after testing, without ANY changes. That's just another release behaviour.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The concept of "pre-release" will mean different things to different parties:

  • Maven: As per example from @ppkarwasz - it was published; it cannot be modified; it is not intended for use in Production systems
  • COTS: E.g. Windows Server 3030 RC (fictitious) - it was published; it cannot be modified; it is not intended for use in Production systems

For me both these examples would be considered as pre-releases by their Manufacturers.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We have had long discussions about this before, but can of course restart if needed.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My only point really is that our definition is not clear in the docs we have. Not that it hasn't been discussed already 😉

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some thoughts on this:

  • We need to be dynamic here -- in some workflows per-releases will not be published, but in other workflows they will (e.g. promoted). Thus, as long as we allow for PATCHing the LEAF to toggle this boolean, we should be good and cover both workflows.
  • NIT: s/alfa/alpha/g and s/prerelease/pre-release/g

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does everyone agree with @vpetersson's conclusion? Does that work for you @ppkarwasz?

I think we still need to add wording to clarify in Docs.

Copy link
Collaborator Author

@oej oej Nov 22, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems like we have a conclusion. What text is needed to clarify more? I tried to be bit fuzzy in the text to not hardcode to a specific example. The flag is meant as a warning to not use this release. We can rename it to "not-recommended" or something along those lines to avoid the discussions about all variants of "beta", "pre-release", "test-release" etc. Just have a marker that the vendor do not recommend using this in production.

We will need a similar flag for when a release is considered dangerous because it contains a vulnerability that's fixed in another release.

madpah marked this conversation as resolved.
Show resolved Hide resolved
creating the LEAF. The TEA implementation may allow it to be unset (False) once. This is to support
situations where a object is promoted as is after testing to production version. The flag can not
be set after initial creation and publication of the leaf.

If the final version is different from the pre-release (bugs fixed, code changed, different binary)
a new leaf with a new UUID and version needs to be created.

## References

Expand Down