sbp commented on code in PR #1221: URL: https://github.com/apache/tooling-trusted-releases/pull/1221#discussion_r3189391689
########## atr/cle.py: ########## @@ -0,0 +1,237 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +"""ECMA-428 Common Lifecycle Enumeration document generator. + +Most of our column names match spec event types directly (eod, eom, eol). +The one translation: `archived` -> `endOfDistribution`. The column name +reflects ATR's action (the release left /dist/release); the spec name +describes the semantic. + +All three event constructors emit `published == effective`. For released +and endOfDistribution that matches the moment of recording. For cycle +events it's a stopgap until semver/calver lands; see _cycle_event. + +We don't emit endOfSupport, withdrawn, endOfMarketing, supersededBy, or +componentRenamed in v1 - spec-conformant absences for #912. +""" + +from __future__ import annotations + +import datetime +from typing import TYPE_CHECKING, Any, Final + +import atr.models.sql as sql + +if TYPE_CHECKING: + from collections.abc import Iterable + +# Versioned schema URL. ECMA-428 is still draft, so this points at the +# tc54 working copy and may need updating when the spec ships. +CLE_SCHEMA_URL: Final[str] = "https://ecma-tc54.github.io/ECMA-428/cle.v1.0.0.schema.json"; + +# CLE event types we currently emit. The spec defines five more we don't: +# endOfSupport, withdrawn, endOfMarketing, supersededBy, componentRenamed. +_RELEASE_EVENT: Final[str] = "released" +_END_OF_DISTRIBUTION_EVENT: Final[str] = "endOfDistribution" +_END_OF_DEVELOPMENT_EVENT: Final[str] = "endOfDevelopment" +_END_OF_MAINTENANCE_EVENT: Final[str] = "endOfMaintenance" Review Comment: I don't see `endOfMaintenance` in [ECMA-428 § 7](https://ecma-tc54.github.io/ECMA-428/#sec-event-types), or anywhere else in the specification. ########## atr/cle.py: ########## @@ -0,0 +1,237 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +"""ECMA-428 Common Lifecycle Enumeration document generator. + +Most of our column names match spec event types directly (eod, eom, eol). +The one translation: `archived` -> `endOfDistribution`. The column name +reflects ATR's action (the release left /dist/release); the spec name +describes the semantic. + +All three event constructors emit `published == effective`. For released +and endOfDistribution that matches the moment of recording. For cycle +events it's a stopgap until semver/calver lands; see _cycle_event. + +We don't emit endOfSupport, withdrawn, endOfMarketing, supersededBy, or +componentRenamed in v1 - spec-conformant absences for #912. +""" + +from __future__ import annotations + +import datetime +from typing import TYPE_CHECKING, Any, Final + +import atr.models.sql as sql + +if TYPE_CHECKING: + from collections.abc import Iterable + +# Versioned schema URL. ECMA-428 is still draft, so this points at the +# tc54 working copy and may need updating when the spec ships. +CLE_SCHEMA_URL: Final[str] = "https://ecma-tc54.github.io/ECMA-428/cle.v1.0.0.schema.json"; + +# CLE event types we currently emit. The spec defines five more we don't: +# endOfSupport, withdrawn, endOfMarketing, supersededBy, componentRenamed. +_RELEASE_EVENT: Final[str] = "released" +_END_OF_DISTRIBUTION_EVENT: Final[str] = "endOfDistribution" +_END_OF_DEVELOPMENT_EVENT: Final[str] = "endOfDevelopment" +_END_OF_MAINTENANCE_EVENT: Final[str] = "endOfMaintenance" +_END_OF_LIFE_EVENT: Final[str] = "endOfLife" + +# Maps internal column names to spec event types. +_CYCLE_EVENT_MAP: Final[tuple[tuple[str, str], ...]] = ( + ("eod", _END_OF_DEVELOPMENT_EVENT), + ("eom", _END_OF_MAINTENANCE_EVENT), + ("eol", _END_OF_LIFE_EVENT), +) + + +def project_document( + project: sql.Project, + cycles: Iterable[sql.ProjectCycle], + releases: Iterable[sql.Release], + *, + now: datetime.datetime, +) -> dict[str, Any]: + """Generate a CLE document covering every event for a project. + + This is the canonical form per ECMA-428: one document per component. + """ + cycles_list = list(cycles) + releases_list = list(releases) + return _document(project, cycles_list, releases_list, now=now) + + +def release_document( + project: sql.Project, + cycle: sql.ProjectCycle, + release: sql.Release, + *, + now: datetime.datetime, +) -> dict[str, Any]: + """Generate a CLE document filtered to a single release. + + This is a derived view, not a spec form. The document still has the + component-level shape ECMA-428 prescribes, but only includes events + touching this release: its own released/archived events, plus the + lifecycle events of the cycle it belongs to. + """ + return _document(project, [cycle], [release], now=now) + + +def _cycle_event( + project: sql.Project, + cycle_releases: list[sql.Release], + event_type: str, + effective: datetime.datetime, +) -> dict[str, Any]: + # Using effective for published until semver/calver lands - cycle phase + # transitions don't have their own publication timestamp yet. + return { + "type": event_type, + "effective": _iso(effective), + "published": _iso(effective), + "versions": [{"range": _vers_for_cycle(project, cycle_releases)}], + } + + +def _document( + project: sql.Project, + cycles: list[sql.ProjectCycle], + releases: list[sql.Release], + *, + now: datetime.datetime, +) -> dict[str, Any]: + return { + "$schema": CLE_SCHEMA_URL, + "identifier": _identifier(project), + "updatedAt": _iso(now), + "events": _events(project, cycles, releases), + } + + +def _end_of_distribution_event(project: sql.Project, release: sql.Release) -> dict[str, Any]: + if release.archived is None: + raise ValueError("endOfDistribution event requires release.archived to be set") + return { + "type": _END_OF_DISTRIBUTION_EVENT, + "effective": _iso(release.archived), + "published": _iso(release.archived), + "versions": [{"range": _vers_literal(project, release.version)}], + } + + +def _events( + project: sql.Project, + cycles: list[sql.ProjectCycle], + releases: list[sql.Release], +) -> list[dict[str, Any]]: + """Build the events list, ordered by effective date then by id descending.""" + + raw: list[dict[str, Any]] = [] + + for release in releases: + if release.released is not None: + raw.append(_released_event(release)) + if release.archived is not None: + raw.append(_end_of_distribution_event(project, release)) + + releases_by_cycle = _releases_by_cycle(releases) + for cycle in cycles: + cycle_releases = releases_by_cycle.get(cycle.cycle_key, []) + for column, event_type in _CYCLE_EVENT_MAP: + date_value = getattr(cycle, column) + if date_value is not None: + raw.append(_cycle_event(project, cycle_releases, event_type, date_value)) + + # Sort ascending by effective date so id assignment is stable for a given Review Comment: From [ECMA-428 § 9](https://ecma-tc54.github.io/ECMA-428/#sec-event-processing-rules): > **Immutability**: Once an event is published, it cannot be modified. New events must be added to correct or update information. [...] **ID Assignment**: Event IDs must be assigned as auto-incrementing integers in the order events are added (not by effective date). But this block of code wouldn't be stable in the current code if we added one in the middle, like an event that we forgot about, or was published by a background task, etc. Might be too hard to fix in the current way that we're doing it, so we'd need a rule to ensure that we can never insert backdated events. ########## atr/cle.py: ########## @@ -0,0 +1,237 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +"""ECMA-428 Common Lifecycle Enumeration document generator. + +Most of our column names match spec event types directly (eod, eom, eol). +The one translation: `archived` -> `endOfDistribution`. The column name +reflects ATR's action (the release left /dist/release); the spec name +describes the semantic. + +All three event constructors emit `published == effective`. For released +and endOfDistribution that matches the moment of recording. For cycle +events it's a stopgap until semver/calver lands; see _cycle_event. + +We don't emit endOfSupport, withdrawn, endOfMarketing, supersededBy, or +componentRenamed in v1 - spec-conformant absences for #912. +""" + +from __future__ import annotations + +import datetime +from typing import TYPE_CHECKING, Any, Final + +import atr.models.sql as sql + +if TYPE_CHECKING: + from collections.abc import Iterable + +# Versioned schema URL. ECMA-428 is still draft, so this points at the +# tc54 working copy and may need updating when the spec ships. +CLE_SCHEMA_URL: Final[str] = "https://ecma-tc54.github.io/ECMA-428/cle.v1.0.0.schema.json"; + +# CLE event types we currently emit. The spec defines five more we don't: +# endOfSupport, withdrawn, endOfMarketing, supersededBy, componentRenamed. +_RELEASE_EVENT: Final[str] = "released" +_END_OF_DISTRIBUTION_EVENT: Final[str] = "endOfDistribution" +_END_OF_DEVELOPMENT_EVENT: Final[str] = "endOfDevelopment" +_END_OF_MAINTENANCE_EVENT: Final[str] = "endOfMaintenance" +_END_OF_LIFE_EVENT: Final[str] = "endOfLife" + +# Maps internal column names to spec event types. +_CYCLE_EVENT_MAP: Final[tuple[tuple[str, str], ...]] = ( + ("eod", _END_OF_DEVELOPMENT_EVENT), + ("eom", _END_OF_MAINTENANCE_EVENT), + ("eol", _END_OF_LIFE_EVENT), +) + + +def project_document( + project: sql.Project, + cycles: Iterable[sql.ProjectCycle], + releases: Iterable[sql.Release], + *, + now: datetime.datetime, +) -> dict[str, Any]: + """Generate a CLE document covering every event for a project. + + This is the canonical form per ECMA-428: one document per component. + """ + cycles_list = list(cycles) + releases_list = list(releases) + return _document(project, cycles_list, releases_list, now=now) + + +def release_document( + project: sql.Project, + cycle: sql.ProjectCycle, + release: sql.Release, + *, + now: datetime.datetime, +) -> dict[str, Any]: + """Generate a CLE document filtered to a single release. + + This is a derived view, not a spec form. The document still has the + component-level shape ECMA-428 prescribes, but only includes events + touching this release: its own released/archived events, plus the + lifecycle events of the cycle it belongs to. + """ + return _document(project, [cycle], [release], now=now) + + +def _cycle_event( + project: sql.Project, + cycle_releases: list[sql.Release], + event_type: str, + effective: datetime.datetime, +) -> dict[str, Any]: + # Using effective for published until semver/calver lands - cycle phase + # transitions don't have their own publication timestamp yet. + return { + "type": event_type, + "effective": _iso(effective), + "published": _iso(effective), + "versions": [{"range": _vers_for_cycle(project, cycle_releases)}], + } + + +def _document( + project: sql.Project, + cycles: list[sql.ProjectCycle], + releases: list[sql.Release], + *, + now: datetime.datetime, +) -> dict[str, Any]: + return { + "$schema": CLE_SCHEMA_URL, + "identifier": _identifier(project), + "updatedAt": _iso(now), + "events": _events(project, cycles, releases), + } + + +def _end_of_distribution_event(project: sql.Project, release: sql.Release) -> dict[str, Any]: + if release.archived is None: + raise ValueError("endOfDistribution event requires release.archived to be set") + return { + "type": _END_OF_DISTRIBUTION_EVENT, + "effective": _iso(release.archived), + "published": _iso(release.archived), + "versions": [{"range": _vers_literal(project, release.version)}], + } + + +def _events( + project: sql.Project, + cycles: list[sql.ProjectCycle], + releases: list[sql.Release], +) -> list[dict[str, Any]]: + """Build the events list, ordered by effective date then by id descending.""" + + raw: list[dict[str, Any]] = [] + + for release in releases: + if release.released is not None: + raw.append(_released_event(release)) + if release.archived is not None: + raw.append(_end_of_distribution_event(project, release)) + + releases_by_cycle = _releases_by_cycle(releases) + for cycle in cycles: + cycle_releases = releases_by_cycle.get(cycle.cycle_key, []) + for column, event_type in _CYCLE_EVENT_MAP: + date_value = getattr(cycle, column) + if date_value is not None: + raw.append(_cycle_event(project, cycle_releases, event_type, date_value)) + + # Sort ascending by effective date so id assignment is stable for a given + # input set. Then emit descending by id, per ECMA-428 Annex B. + raw.sort(key=lambda event: (event["effective"], event["type"])) + for index, event in enumerate(raw, start=1): + event["id"] = index + raw.reverse() + return raw + + +def _identifier(project: sql.Project) -> str: + """Render the project as a Package-URL. + + `pkg:apache/<project_key>` is the simplest form. Per-distribution PURLs + (`pkg:maven/...`, `pkg:pypi/...`) belong on the artifact catalog (#911), + not on the lifecycle doc. This may change with outcome of https://github.com/package-url/purl-spec/issues/516 + """ + return f"pkg:apache/{project.key}" + + +def _iso(value: datetime.datetime) -> str: + """Render a UTC datetime as ISO 8601 with a Z suffix.""" + if value.tzinfo is None: + value = value.replace(tzinfo=datetime.UTC) + else: + value = value.astimezone(datetime.UTC) + return value.isoformat().replace("+00:00", "Z") + + +def _released_event(release: sql.Release) -> dict[str, Any]: + if release.released is None: + raise ValueError("released event requires release.released to be set") + return { + "type": _RELEASE_EVENT, + "effective": _iso(release.released), + "published": _iso(release.released), + "version": release.version, + } + + +def _releases_by_cycle(releases: list[sql.Release]) -> dict[str, list[sql.Release]]: + grouped: dict[str, list[sql.Release]] = {} + for release in releases: + grouped.setdefault(release.cycle_key, []).append(release) + return grouped + + +def _vers_for_cycle(project: sql.Project, cycle_releases: list[sql.Release]) -> str: + """Render a VERS range for every version in a cycle. + + For a cycle with no releases yet we emit a wildcard - the lifecycle event + applies to all versions in the (currently empty) cycle. With releases, we + emit a literal pipe-delimited list of every version, which is correct + regardless of version_method but verbose for large cycles. Once semver + projects exist, this can return a proper range like + `vers:semver/>=2.0.0|<3.0.0` derived from cycle_match. + """ + scheme = _vers_scheme(project) + if not cycle_releases: + return f"vers:{scheme}/*" + constraints = "|".join(f"={r.version}" for r in cycle_releases) Review Comment: Looking at [ECMA-428 § Annex A](https://ecma-tc54.github.io/ECMA-428/#sec-vers), it appears that the literal version syntax is just the version with no prefix. There's no `=1.2.3` in there. ########## atr/cle.py: ########## @@ -0,0 +1,237 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +"""ECMA-428 Common Lifecycle Enumeration document generator. + +Most of our column names match spec event types directly (eod, eom, eol). +The one translation: `archived` -> `endOfDistribution`. The column name +reflects ATR's action (the release left /dist/release); the spec name +describes the semantic. + +All three event constructors emit `published == effective`. For released +and endOfDistribution that matches the moment of recording. For cycle +events it's a stopgap until semver/calver lands; see _cycle_event. + +We don't emit endOfSupport, withdrawn, endOfMarketing, supersededBy, or +componentRenamed in v1 - spec-conformant absences for #912. +""" + +from __future__ import annotations + +import datetime +from typing import TYPE_CHECKING, Any, Final + +import atr.models.sql as sql + +if TYPE_CHECKING: + from collections.abc import Iterable + +# Versioned schema URL. ECMA-428 is still draft, so this points at the +# tc54 working copy and may need updating when the spec ships. +CLE_SCHEMA_URL: Final[str] = "https://ecma-tc54.github.io/ECMA-428/cle.v1.0.0.schema.json"; + +# CLE event types we currently emit. The spec defines five more we don't: +# endOfSupport, withdrawn, endOfMarketing, supersededBy, componentRenamed. +_RELEASE_EVENT: Final[str] = "released" +_END_OF_DISTRIBUTION_EVENT: Final[str] = "endOfDistribution" +_END_OF_DEVELOPMENT_EVENT: Final[str] = "endOfDevelopment" +_END_OF_MAINTENANCE_EVENT: Final[str] = "endOfMaintenance" +_END_OF_LIFE_EVENT: Final[str] = "endOfLife" + +# Maps internal column names to spec event types. +_CYCLE_EVENT_MAP: Final[tuple[tuple[str, str], ...]] = ( + ("eod", _END_OF_DEVELOPMENT_EVENT), + ("eom", _END_OF_MAINTENANCE_EVENT), + ("eol", _END_OF_LIFE_EVENT), +) + + +def project_document( + project: sql.Project, + cycles: Iterable[sql.ProjectCycle], + releases: Iterable[sql.Release], + *, + now: datetime.datetime, +) -> dict[str, Any]: + """Generate a CLE document covering every event for a project. + + This is the canonical form per ECMA-428: one document per component. + """ + cycles_list = list(cycles) + releases_list = list(releases) + return _document(project, cycles_list, releases_list, now=now) + + +def release_document( + project: sql.Project, + cycle: sql.ProjectCycle, + release: sql.Release, + *, + now: datetime.datetime, +) -> dict[str, Any]: + """Generate a CLE document filtered to a single release. + + This is a derived view, not a spec form. The document still has the + component-level shape ECMA-428 prescribes, but only includes events + touching this release: its own released/archived events, plus the + lifecycle events of the cycle it belongs to. + """ + return _document(project, [cycle], [release], now=now) + + +def _cycle_event( Review Comment: https://ecma-tc54.github.io/ECMA-428/#sec-event-type-endofdevelopment https://ecma-tc54.github.io/ECMA-428/#sec-event-type-endofsupport These also require a `supportId` attribute. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
