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

Add XSD schema to support info plugin's GH repo #1

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add XSD schema to support info plugin's GH repo #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
14 changes: 14 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,20 @@ More information as to the maintenance support period of Amazon Linux 2022 can b

The full list of core packages will be finalized during the preview. If you want to see more packages included as core packages, tell us. We will evaluate as we are collecting feedback. Feedback on Amazon Linux 2022 can be provided through your designated AWS representative or [Amazon Linux Discussion Forums](https://forums.aws.amazon.com/forum.jspa?forumID=228).

## Schema for support_info.xml file:
Copy link
Member

Choose a reason for hiding this comment

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

Suggest we just have something shorter here, as we don't need to give the example of the makefile

+## Schema for support_info.xml file:
+
+You can validate a `support_info.xml` file against the provided XSD schema using `xmllint`:
+
+```
+xmllint --noout --schema support_info.xsd support_info.xml
+```

Invoking it as part of building the package would only be needed if doing the generation here, which would likely be a different generate.py script rather than the main package.


Amazon Linux developed an internal tooling which uses `repoquery` to generate the `support_info.xml` file. The elements of that XML file are defined by an XSD schema, file has been added under `configurations/` dir, and it can be tested with the `make` command when the Makefile has -

```

SUPPORT_INFO_SCHEMA = configuration/support_info.xsd
SUPPORT_INFO_FILE = support_info.xml

test: lint
lint: $(SUPPORT_INFO_SCHEMA) $(SUPPORT_INFO_FILE)
xmllint --noout --schema $(SUPPORT_INFO_SCHEMA) $(SUPPORT_INFO_FILE)

```

## Plugin Usage:

Expand Down
129 changes: 129 additions & 0 deletions configurations/support_info.xsd
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,129 @@
<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
attributeFormDefault="unqualified">

<xs:annotation>
<xs:appinfo>Support Info XML</xs:appinfo>
<xs:documentation xml:lang="en">
This schema defines a document that describes the support statements
for RPM packages in a YUM repository. This allows a user to map what
packages they have installed to a support statement both as of now,
and into the future. It also allows an OS vendor to deprecate parts
of the Operating System before other parts in order to provide extended
support, and for that to be clear and machine readable.
</xs:documentation>
</xs:annotation>

<xs:element name="package_support" type="PackageSupport">
<xs:annotation>
<xs:documentation xml:lang="en">
The top level package_support element contains support statements, notes on
those statements, along with a single top level attribute on when the package
support statement is current as of.
</xs:documentation>
</xs:annotation>
</xs:element>

<xs:complexType name="PackageSupport">
<xs:all>
<xs:element name="statements" type="Statements" minOccurs="1" maxOccurs="1" />
<xs:element name="notes" type="Notes" minOccurs="0" maxOccurs="1" />
</xs:all>
<xs:attribute name="current_as" type="xs:dateTime" />
</xs:complexType>

<xs:complexType name="Statements">
<xs:sequence>
<xs:element name="statement" type="Statement" minOccurs="1" maxOccurs="unbounded">
<xs:annotation>
<xs:documentation xml:lang="en">
The main part of this document is a series of statements about particular
packages. Optionally, these statements have start and end dates. These dates
can be used to transition packages through different support phases, and out
to a final unsupported state.
</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>

<xs:complexType name="Statement">
<xs:sequence>
<xs:element name="summary" type="xs:string" minOccurs="1"/>
<xs:element name="text" type="xs:string" minOccurs="1"/>
<xs:element name="link" type="xs:string" minOccurs="1" maxOccurs="1"/>
<xs:element name="packages" type="Packages" minOccurs="1" maxOccurs="1"/>
</xs:sequence>
<xs:attribute name="id" type="xs:string" use="required">
<xs:annotation>
<xs:documentation xml:lang="en">
A unique (for the document) identifier. Must conform with requirements for
a html anchor name.
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="start_date" type="xs:date"/>
<xs:attribute name="end_date" type="xs:date"/>
<xs:attribute name="marker" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en">
The marker indicates what kind of statement this is, and thus can be used
by compliance software to join the set of installed packages with a policy
as to what's allowed.
A value of 'unsupported' means that this statement is about the non-support
of software. A value of 'supported' means that it's a positive affirmation
of support.
</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>

<xs:complexType name="Notes">
<xs:sequence>
<xs:element name="note" type="Note" minOccurs="0" maxOccurs="unbounded">
<xs:annotation>
<xs:documentation xml:lang="en">
Matching a package to a support statement can come with an additional note
as to why that particular package is there. For example, as part of a deprecation
campaign for a custom OS inside a company, one could deprecate all packages that
aren't installed on any host, and indicate that in a note. A note is designed
to be useful to someone wondering why a package is in a particular category.
</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>

<xs:complexType name="Packages">
<xs:sequence>
<xs:element name="package" type="Package" minOccurs="1" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>

<xs:complexType name="Note">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="id" type="xs:string"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>


<xs:complexType name="Package">
<xs:sequence>
<xs:element name="max_version" type="Version" minOccurs="0" maxOccurs="1"/>
Copy link
Member

Choose a reason for hiding this comment

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

We need to have it documented if this is inclusive or not.

I would suggest we say that it is inclusive.

that is, if we have <package name="kernel"><max_version version="4.14.4000" release="5000.distag"/></package> it would mean that the statement applies to all versions up to including kernel-4.14.4000-5000.disttag.

<xs:element name="min_version" type="Version" minOccurs="0" maxOccurs="1"/>
</xs:sequence>
<xs:attribute name="name" type="xs:string"/>
<xs:attribute name="note" type="xs:string"/>
</xs:complexType>

<xs:complexType name="Version">
<xs:attribute name="arch" type="xs:string"/>
Copy link
Member

Choose a reason for hiding this comment

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

Is the intent here that we specify all arches that we have built, and thus the code doing the comparison needs to do this comparison?

<xs:attribute name="epoch" type="xs:string"/>
Copy link
Member

Choose a reason for hiding this comment

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

this should be optional, and documented as such, defaulting to zero.

<xs:attribute name="release" type="xs:string"/>
<xs:attribute name="version" type="xs:string"/>
</xs:complexType>
Copy link
Member

Choose a reason for hiding this comment

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

We should very much have tests and examples here.


</xs:schema>