From c87db4ad430a30a5cea78cb1019bb2730abba2c5 Mon Sep 17 00:00:00 2001 From: "David E. Wheeler" Date: Wed, 26 Jun 2024 19:09:42 -0400 Subject: [PATCH] Update spec to v1.0.1 --- Changes | 2 + doc/spec.txt | 630 +++++++++++++++++++++++++++------------------------ 2 files changed, 330 insertions(+), 302 deletions(-) diff --git a/Changes b/Changes index 9f19820..456245d 100644 --- a/Changes +++ b/Changes @@ -1,6 +1,8 @@ Revision history for Perl extension PGXN::Manager 0.32.1 + - Updated `doc/spec.txt` to v1.0.1, from it new home in + https://github.com/pgxn/pgxn-meta-spec. 0.32.0 2024-02-17T17:25:24Z - Combined the pgxn_consumer PID number and file location into one diff --git a/doc/spec.txt b/doc/spec.txt index 65ee982..62918ca 100644 --- a/doc/spec.txt +++ b/doc/spec.txt @@ -6,88 +6,87 @@ PGXN Meta Spec - The PGXN distribution metadata specification Version ======= -1.0.0 +1.0.1 Synopsis ======== - { - "name": "pgTAP", - "abstract": "Unit testing for PostgreSQL", - "description": "pgTAP is a suite of database functions that make it easy to write TAP-emitting unit tests in psql scripts or xUnit-style test functions.", - "version": "0.2.5", - "maintainer": [ - "David E. Wheeler ", - "pgTAP List " - ], - "license": { - "PostgreSQL": "https://www.postgresql.org/about/licence" - }, - "prereqs": { - "runtime": { - "requires": { - "plpgsql": 0, - "PostgreSQL": "8.0.0" - }, - "recommends": { - "PostgreSQL": "8.4.0" - } - } - }, - "provides": { - "pgtap": { - "file": "sql/pgtap.sql", - "docfile": "doc/pgtap.mmd", - "version": "0.2.4", - "abstract": "Unit testing assertions for PostgreSQL" - }, - "schematap": { - "file": "sql/schematap.sql", - "docfile": "doc/schematap.mmd", - "version": "0.2.4", - "abstract": "Schema testing assertions for PostgreSQL" - } - }, - "resources": { - "homepage": "https://pgtap.org/", - "bugtracker": { - "web": "https://github.com/theory/pgtap/issues" - }, - "repository": { - "url": "https://github.com/theory/pgtap.git", - "web": "https://github.com/theory/pgtap", - "type": "git" - } - }, - "generated_by": "David E. Wheeler", - "meta-spec": { - "version": "1.0.0", - "url": "https://pgxn.org/meta/spec.txt" - }, - "tags": [ - "testing", - "unit testing", - "tap", - "tddd", - "test driven database development" - ] +``` json +{ + "name": "pgTAP", + "abstract": "Unit testing for PostgreSQL", + "description": "pgTAP is a suite of database functions that make it easy to write TAP-emitting unit tests in psql scripts or xUnit-style test functions.", + "version": "0.2.5", + "maintainer": [ + "David E. Wheeler ", + "pgTAP List " + ], + "license": { + "PostgreSQL": "https://www.postgresql.org/about/licence" + }, + "prereqs": { + "runtime": { + "requires": { + "plpgsql": 0, + "PostgreSQL": "8.0.0" + }, + "recommends": { + "PostgreSQL": "8.4.0" + } + } + }, + "provides": { + "pgtap": { + "file": "sql/pgtap.sql", + "docfile": "doc/pgtap.mmd", + "version": "0.2.4", + "abstract": "Unit testing assertions for PostgreSQL" + }, + "schematap": { + "file": "sql/schematap.sql", + "docfile": "doc/schematap.mmd", + "version": "0.2.4", + "abstract": "Schema testing assertions for PostgreSQL" + } + }, + "resources": { + "homepage": "https://pgtap.org/", + "bugtracker": { + "web": "https://github.com/theory/pgtap/issues" + }, + "repository": { + "url": "https://github.com/theory/pgtap.git", + "web": "https://github.com/theory/pgtap", + "type": "git" } + }, + "generated_by": "David E. Wheeler", + "meta-spec": { + "version": "1.0.0", + "url": "https://pgxn.org/meta/spec.txt" + }, + "tags": [ + "testing", + "unit testing", + "tap", + "tddd", + "test driven database development" + ] +} +``` Description =========== This document describes version 1.0.0 of the PGXN distribution metadata -specification, also known as the “PGXN Meta Spec.” It is formatted using the -[MultiMarkdown](https://fletcherpenney.net/multimarkdown/) variant of -[Markdown](https://daringfireball.net/projects/markdown/), and the canonical -copy may always be found at -[master.pgxn.org/meta/spec.txt](https://master.pgxn.org/meta/spec.txt). A -generated HTML-formatted copy found at [pgxn.org/spec/](https://pgxn.org/spec/) -may also be considered canonical. +specification, also known as the "PGXN Meta Spec." It is formatted using the +[Github Flavored Markdown] variant of [Markdown], and the canonical copy may +always be found at [master.pgxn.org/meta/spec.txt]. A generated HTML-formatted +copy found at [pgxn.org/spec/] may also be considered canonical. This document is stable. Any revisions to this specification for typo -corrections and prose clarifications may be issued as “PGXN Meta Spec -1.0.*x*”. These revisions will never change semantics or add or remove +corrections and prose clarifications may be issued as "PGXN Meta Spec +1.0.*x*". These revisions will never change semantics or add or remove specified behavior. Distribution metadata describe important properties of PGXN distributions. @@ -102,31 +101,27 @@ distribution : The primary object described by the metadata. In the context of this document it usually refers to a collection of extensions, source code, utilities, tests, and/or documents that are distributed together for other - developers to use. Examples of distributions are - [`semver`](https://pgxn.org/dist/semver/), - [`pair`](https://pgxn.org/dist/pair/), and - [`pgTAP`](https://pgxn.org/dist/pgTAP/). + developers to use. Examples of distributions are [`semver`], [`pair`], and + [`pgTAP`]. extension : A reusable library of code contained in a single file or within files - referenced by the [`CREATE EXTENSION` - statement](https://www.postgresql.org/docs/current/static/sql-createextension.html). - Extensions usually contain one or more PostgreSQL objects — such as data - types, functions, and operators — and are often referred to by the name of - a primary object that can be mapped to the file name. For example, one - might refer to `pgTAP` instead of `sql/pgtap.sql`. + referenced by the [`CREATE EXTENSION` statement]. Extensions usually + contain one or more PostgreSQL objects --- such as data types, functions, + and operators --- and are often referred to by the name of a primary + object that can be mapped to the file name. For example, one might refer + to `pgTAP` instead of `sql/pgtap.sql`. consumer : Code that reads a metadata file, deserializes it into a data structure in memory, or interprets a data structure of metadata elements. producer -: Code that constructs a metadata data structure, serializes into a - bytestream and/or writes it to disk. +: Code that constructs a metadata data structure, serializes into a byte + stream and/or writes it to disk. must, should, may, etc. -: These terms are interpreted as described in [IETF RFC - 2119](https://www.ietf.org/rfc/rfc2119.txt). +: These terms are interpreted as described in [IETF RFC 2119]. Data Types ========== @@ -165,8 +160,8 @@ to a List of length 1. Map --- -A *Map* is an unordered collection of zero or more data elements (“values”), -indexed by associated [String](#String) elements (“keys”). The Map’s value +A *Map* is an unordered collection of zero or more data elements ("values"), +indexed by associated [String](#String) elements ("keys"). The Map’s value elements may be of mixed types. License String @@ -219,9 +214,9 @@ describes valid keys within the [Map](#Map). Any keys not described in this specification document (whether top-level or within compound data structures described herein) are considered *custom keys* -and **must** begin with an “x” or “X” and be followed by an underscore; i.e. +and **must** begin with an "x" or "X" and be followed by an underscore; i.e.l, they must match the pattern: `/\Ax_/i`. If a custom key refers to a compound -data structure, subkeys within it do not need an “x_” or “X_” prefix. +data structure, subkeys within it do not need an "x_" or "X_" prefix. Consumers of metadata may ignore any or all custom keys. All other keys not described herein are invalid and should be ignored by consumers. Producers @@ -234,7 +229,7 @@ which the definition was modified, whether the key is *required* or are in parentheses, brackets, and braces, respectively. If a data type is a [Map](#Map) or [Map](#Map) subtype, valid subkeys will be -described as well. All examples are represented as [JSON](https://json.org/). +described as well. All examples are represented as [JSON]. - -configure -: The configure phase occurs before any dynamic configuration has been - attempted. Extensions required by the configure phase **must** be +* **configure**: The configure phase occurs before any dynamic configuration + has been attempted. Extensions required by the configure phase **must** be available for use before the distribution building tool has been executed. -build -: The build phase is when the distribution’s source code is compiled (if - necessary) and otherwise made ready for installation. +* **build**: The build phase is when the distribution’s source code is + compiled (if necessary) and otherwise made ready for installation. -test -: The test phase is when the distribution’s automated test suite is run. Any - extension needed only for testing and not for subsequent use should be - listed here. +* **test**: The test phase is when the distribution’s automated test suite + is run. Any extension needed only for testing and not for subsequent use + should be listed here. -runtime -: The runtime phase refers not only to when the distribution’s contents are - installed, but also to its continued use. Any extension that is a - prerequisite for regular use of this distribution should be indicated +* **runtime**: The runtime phase refers not only to when the distribution’s + contents are installed, but also to its continued use. Any extension that + is a prerequisite for regular use of this distribution should be indicated here. -develop -: The develop phase’s prereqs are extensions needed to work on the - distribution’s source code as its maintainer does. These tools might be - needed to build a release tarball, to run maintainer-only tests, or to +* **develop**: The develop phase’s prereqs are extensions needed to work on + the distribution’s source code as its maintainer does. These tools might + be needed to build a release tarball, to run maintainer-only tests, or to perform other tasks related to developing new versions of the distribution. @@ -773,7 +785,6 @@ suggests of the described distribution. conflicts - : These dependencies cannot be installed when the phase is in operation. This is a very rare situation, and the conflicts relationship should be used with great caution, or not at all. @@ -797,18 +808,18 @@ mappings: Extension | Version | Distribution ------------|---------|------------------ - pgtap | 0.25.0 | pgTAP-0.25.0.zip - schematap | 0.25.0 | pgTAP-0.25.0.zip - functap | 0.18.1 | pgTAP-0.18.1.zip + pgtap | 0.25.0 | pgtap-0.25.0.zip + schematap | 0.25.0 | pgtap-0.25.0.zip + functap | 0.18.1 | pgtap-0.18.1.zip -Note that functap was removed from the pgTAP distribution sometime after -0.18.1. Consider the case where pgTAP 0.25.0 is installed. If a distribution -specified “functap” as a prerequisite, it could result in -`pgTAP-0.18.1.tar.gz` being installed, overwriting any files from -`pgTAP-0.25.0.zip`. +Note that functap was removed from the pgtap distribution sometime after +0.18.1. Consider the case where pgtap 0.25.0 is installed. If a distribution +specified "functap" as a prerequisite, it could result in +`pgtap-0.18.1.tar.gz` being installed, overwriting any files from +`pgtap-0.25.0.zip`. Consumers of metadata **should** test whether prerequisites would result in -installed module files being “downgraded” to an older version and **may** warn +installed module files being "downgraded" to an older version and **may** warn users or ignore the prerequisite that would cause such a result. Serialization @@ -823,32 +834,47 @@ Notes For Implementors Comparing Version Numbers ------------------------- -Following the [Semantic Versioning Spec](https://semver.org/), version numbers -**must** be strictly compared by splitting the [Version](#Version) -string on full stop characters (i.e. “dots”, “periods” or “decimal points”) -and comparing each of the three parts as integers. If an ASCII string has been -appended to the third number, it will be extracted and compared in -ASCII-betical order, and in any event will be considered to be less than an -un-encumbered third integer of the same value. Some examples: - - 0.12.1 < 0.12.2 - 1.42.0 > 1.41.99 - 2.0.0 > 1.999.999 - 2.0.0alpha3 < 2.0.0beta1 - 2.0.0beta < 2.0.0 +Following the [Semantic Versioning 2.0.0 Spec][semver], version numbers +**must** be strictly compared by splitting the [Version](#Version) string on +full stop characters (i.e. "dots", "periods" or "decimal points") and +comparing each of the three parts as integers. If a dash and prerelease ASCII +string has been appended to the third number, it will be extracted and +compared in ASCII-betical order, and in any event will be considered to be +less than an un-encumbered third integer of the same value. Some examples: + +``` +0.12.1 < 0.12.2 +1.42.0 > 1.41.99 +2.0.0 > 1.999.999 +2.0.0alpha3 < 2.0.0beta1 +2.0.0beta < 2.0.0 +``` See Also ======== -* [CPAN Meta Spec](https://metacpan.org/pod/CPAN::Meta::Spec) -* [PGXN](https://www.pgxn.org/) -* [JSON](https://json.org/) -* [Semantic Versioning](https://semver.org/) +* [CPAN Meta Spec] +* [PGXN] +* [JSON] +* [Semantic Versioning 2.0.0][semver] Contributors ============ -The PGXN Meta Spec borrows heavily from the [CPAN Meta -Spec](https://metacpan.org/pod/CPAN::Meta::Spec), which was originally -written by Ken Williams in 2003 and has since been updated by Randy Sims, -David Golden, and Ricardo Signes. Ported to PGXN by David E. Wheeler. +The PGXN Meta Spec borrows heavily from the [CPAN Meta Spec], which was +originally written by Ken Williams in 2003 and has since been updated by Randy +Sims, David Golden, and Ricardo Signes. Ported to PGXN by David E. Wheeler. + + [Github Flavored Markdown]: https://github.github.com/gfm/ + [Markdown]: https://daringfireball.net/projects/markdown/ + [master.pgxn.org/meta/spec.txt]: https://master.pgxn.org/meta/spec.txt + [pgxn.org/spec/]: https://pgxn.org/spec/ + [`semver`]: https://pgxn.org/dist/semver/ + [`pair`]: https://pgxn.org/dist/pair/ + [`pgTAP`]: https://pgxn.org/dist/pgtap/ + [`CREATE EXTENSION` statement]: https://www.postgresql.org/docs/current/static/sql-createextension.html + [IETF RFC 2119]: https://www.ietf.org/rfc/rfc2119.txt + [JSON]: https://json.org/ + [semver]: https://semver.org/ + [CPAN Meta Spec]: https://metacpan.org/pod/CPAN::Meta::Spec + [PGXN]: https://pgxn.org/