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.

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

RFC: Meta Spec v2 #3

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

RFC: Meta Spec v2 #3

wants to merge 10 commits into from

Conversation

theory
Copy link
Member

@theory theory commented Jul 11, 2024

Add a new RFC for Meta Spec v2. Based on the PGXN Meta Sketch and additional research. Notable differences from v1:

  • Introduce the term "package" separate from "distribution". The "package" is the bundle of objects being distributed as a…package.
  • Use only one version for the entire distribution, rather than separate versions for each extension included in the distribution. This allows the deletion of the notes on comparing versions.
  • Make "Source Distribution" the formal term, but mostly refer to it as "Distribution". Will be distinguished from binary distributions that ship with their own metadata (see RFC: Binary Distribution Format #2).
  • Use JSON data types as the base types instead of generic "list" and "map" types.
  • Add "Path", "purl", and "Platform" types
  • Use SPDX License Expressions instead of Perl Software::License-based structures.
  • Use the term "property" to describe object key/value pairs, to align with JSON Schema.
  • Use an array of objects to describe maintainers.
  • Replace the provides property with contents, with support for multiple kinds of PostgreSQL extensions, including TLEs, loadable modules, and background workers.
  • Move the tags property to the new classifications object, and add support for curated categories borrowed from Trunk.
  • Replace no_index with ignore and use the gitignore format instead of separate lists of files and directories.
  • Rename prereqs to packages and move it into the new dependencies property, which also has postgres, pipeline, platforms, and variations properties. Use purls to specify dependencies, so that any supported packaging dependency can be specified, as well as PGXN packages and Postgres core extensions and tools.
  • Remove release_status; we'll instead depend on SemVer to indicate pre-releases.
  • Simplify the resources object and add badges to it.
  • Add the artifacts property, so the extension author can include links to other packages or sources for a release.

Also configure # to hide a line in json code blocks and use it to encode proper JSON objects without showing the surrounding braces. Readers can hit the eye button that appears on hover to make the hidden lines appear.

@theory theory added the documentation Improvements or additions to documentation label Jul 11, 2024
@theory theory self-assigned this Jul 11, 2024
@theory theory force-pushed the meta-spec-v2 branch 2 times, most recently from 7f30c48 to 9f7718b Compare July 11, 2024 21:53
@theory theory added rfc New RFC and removed documentation Improvements or additions to documentation labels Jul 11, 2024
@theory theory mentioned this pull request Jul 12, 2024
2 tasks
Add a new RFC for Meta Spec v2. Based on the [PGXN Meta Sketch] and
additional research. Notable differences from v1:

*   Introduce the term "package" separate from "distribution". The
    "package" is the bundle of objects being distributed as a…package.
*   Use only one version for the entire distribution, rather than
    separate versions for each extension included in the distribution.
    This allows the deletion of the notes on comparing versions.
*   Make "Source Distribution" the formal term, but mostly refer to it
    as "Distribution". Will be distinguished from binary distributions
    that ship with their own metadata (see #2).
*   Use JSON data types as the base types instead of generic "list" and
    "map" types.
*   Add "Path", "purl", and "Platform" types
*   Use SPDX License Expressions instead of Perl Software::License-based
    structures.
*   Use the term "property" to describe object key/value pairs, to align
    with JSON Schema.
*   Use an array of objects to describe maintainers.
*   Replace the `provides` property with `contents`, with support for
    multiple kinds of PostgreSQL extensions, including TLEs, loadable
    modules, and background workers.
*   Move the `tags` property to the new `classifications` object, and
    add support for curated categories borrowed from [Trunk].
*   Replace `no_index` with `ignore` and use the gitignore format
    instead of separate lists of files and directories.
*   Rename `prereqs` to `packages` and move it into the new
    `dependencies` property, which also has `postgres`, `pipeline`,
    `platforms`, and `variations` properties. Use [purls]. to specify
    dependencies, so that any supported packaging dependency can be
    specified, as well as PGXN packages and Postgres core extensions and
    tools.
*   Remove `release_status`; we'll instead depend on [SemVer] to
    indicate pre-releases.
*   Simplify the `resources` object and add `badges` to it.
*   Add the `artifacts` property, so the extension author can include
    links to other packages or sources for a release.

Also configure `#` to hide a line in `json` code blocks and use it to
encode proper JSON objects without showing the surrounding braces.
Readers can hit the eye button that appears on hover to make the hidden
lines appear.

[PGXN Meta Sketch]: https://justatheory.com/2024/03/rfc-pgxn-metadata-sketch/
[Trunk]: https://pgt.dev
[purls]: https://github.com/package-url/purl-spec/blob/master/PURL-SPECIFICATION.rs
[SemVer] https://semver.org
*   Add the "Package Name" type that disallows leading digits.
    [Discussion](#2 (comment)).
*   Document the Number type and allow `0` as a valid value for a
    Version Range.
*   Add the "Path Pattern" type and use it for the "ignore" property.
*   Merge "License" into "License Expression"
*   Rename "Version" to "SemVer", to distinguish it from any other
    versions used for dependencies.
*   Make "Version Range" not-specific to SemVers, since it's used for
    all sorts of dependency version requirements. Also, disallow version
    truncation in Version Ranges, since different version formats will
    have different rules.
*   Document that purl version expressions are valid but ignored.
*   Fix various spelling, grammatical, syntax, and narrative errors and
    clumsiness.
*   Update spec URLs to point to rfcs.pgxn.org.
*   Rename `generated_by` to `producer`.
*   Add question about preloading.
*   Note quality binary distribution as sign of success.
Instead of having a separate "package name" type. A quick check of the
PGXN database and [1000+ PostgreSQL EXTENSIONs] shows no existing
extensions contain a dot. This will simplify parsing a package name from
a semver in file names, since dots are required for semantic versions.

  [1000+ PostgreSQL EXTENSIONs]: https://gist.github.com/joelonsql/e5aa27f8cc9bd22b8999b7de8aee9d47
* extensions: `CREATE EXTENSION` extensions
* modules: loadable modules for extensions, hooks, and workers
* apps: Programs and scripts like pg_top, pgAdmin, or pg_partman scripts

Add an example from pg_partman, which includes all three types.
*   Add missing `contents` key to example
*   Rename "Path Pattern" to "Glob"
*   Fix ignore header
*   Fix missing package version
*   Use "cargo" instead of "rust" for pipeline value
*   Tweak wording on phases
*   Add url property to badge
theory added a commit to pgxn/meta that referenced this pull request Jul 24, 2024
Based on pgxn/rfcs#3. As with the v1 schemas, use JSON Schema v2020 for
the v2 schemas.

Fix a few minor issues with the v1 schema, as well. Add full test suite
in Rust; move code shared between the v1 and v2 tests to
`tests/common/mod.rs`. This includes custom format functions not
required for v1, including spdx version expression validation with the
`spdx` crate, and path validation to ensure no `..` is included in
paths.
theory added a commit to pgxn/meta that referenced this pull request Jul 24, 2024
Based on pgxn/rfcs#3. As with the v1 schemas, use JSON Schema v2020 for
the v2 schemas.

Fix a few minor issues with the v1 schema, as well. Add full test suite
in Rust; move code shared between the v1 and v2 tests to
`tests/common/mod.rs`. This includes custom format functions not
required for v1, including spdx version expression validation with the
`spdx` crate, and path validation to ensure no `..` is included in
paths.
Also link to the Repology API.
And fix a couple of version references and links.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
rfc New RFC
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant