Do some housekeeping in preparation for release

*   Increment version to v0.2.0.
*   Flesh out the Changelog.
*   Switch to the `theory/changelog-version-notes-action` to generate
    release notes.
*   Make the `meta` module public.
*   Make the `valid` module public and remove its importation from the
    crate root.
*   Move the validation example to the `valid` module.
*   Make the `try_from(meta: &[&Value])` documentation visible and start
    thinking through documentation for the `meta` module.

.github/workflows/build-and-release.yml

@@ -210,14 +210,15 @@ jobs:
               exit 1
           fi
         if: matrix.toolchain == 'stable' && startsWith( github.ref, 'refs/tags/v' )
-      - name: Generate Release Changes
-        run: make target/release-notes.md
-        if: matrix.toolchain == 'stable' && startsWith( github.ref, 'refs/tags/v' )
+      - name: Generate Release Notes
+        id: notes
+        uses: theory/changelog-version-notes-action@v0
+        with: { version: "${{ env.VERSION }}" }
       - name: Publish GitHub Release
         uses: softprops/action-gh-release@v2
         with:
           draft: true
           name: "Relelase ${{ env.VERSION }}"
           files: "pgxn_meta-*"
-          body_path: target/release-notes.md
+          body_path: ${{ steps.notes.outputs.file }}
         if: matrix.toolchain == 'stable' && startsWith( github.ref, 'refs/tags/v' )

CHANGELOG.md

@@ -7,8 +7,32 @@ All notable changes to this project will be documented in this file. It uses the
   [Semantic Versioning]: https://semver.org/spec/v2.0.0.html
     "Semantic Versioning 2.0.0"
 
-## [Unreleased] — Date TBD
+## [v0.2.0] — Date TBD
 
+### ⚡ Improvements
+
+*   Added the [meta module], which loads v1 and v2 spec files, converts v1
+    metadata to v2, and merges multiple files.
+
+### 🪲 Bug Fixes
+
+*   Changed the v1 validator to allow `http` as well as `https` in the
+    `meta-spec` object's `url` field, as a lot of older `META.json` files use
+    it.
+
+### 📔 Notes
+
+*   Moved the validation functionality to the [valid module].
+
+### 📚 Documentation
+
+*   Updated the `v2` link in all docs to point to the [pull request], since it
+    hasn't been merged and published yet.
+
+  [v0.2.0]: https://github.com/pgxn/meta/compare/v0.1.0...v0.2.0
+  [meta module]: https://docs.rs/pgxn_meta/meta/
+  [valid module]: https://docs.rs/pgxn_meta/meta/
+  [pull request]: https://github.com/pgxn/rfcs/pull/3 "pgxn/rfcs#3 Meta Spec v2"
 
 ## [v0.1.0] — 2024-08-08
 

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pgxn_meta"
-version = "0.1.0"
+version = "0.2.0"
 description = "The PGXN distribution metadata specification"
 repository = "https://github.com/pgxn/pgxn-meta-spec"
 documentation = "https://docs.rs/pgxn_meta/"

Makefile

@@ -21,5 +21,7 @@ docs: target/doc/pgxn_meta/index.html
 target/doc/pgxn_meta/index.html: $(shell find . -name \*.rs)
 	cargo doc
 
-target/release-notes.md: CHANGELOG.md .ci/mknotes Cargo.toml
-	@./.ci/mknotes -f $< -r https://github.com/$(or $(GITHUB_REPOSITORY),pgxn/meta) -o $@
+VERSION = $(shell perl -nE '/^version\s*=\s*"([^"]+)/ && do { say $$1; exit }' Cargo.toml)
+.PHONY: release-notes # Show release notes for current version (must have `mknotes` in PATH).
+release-notes: CHANGELOG.md
+	mknotes -v v$(VERSION) -f $< -r https://github.com/$(or $(GITHUB_REPOSITORY),pgxn/meta)

src/lib.rs

@@ -3,48 +3,17 @@
 /*!
 PGXN Metadata validation.
 
-This crate uses JSON Schema to validate PGXN Meta Spec `META.json` files.
-It supports both the [v1] and [v2] specs.
-
-# Example
-
-``` rust
-use std::{path::PathBuf, error::Error};
-use serde_json::json;
-use pgxn_meta::*;
-
-let meta = json!({
-  "name": "pair",
-  "abstract": "A key/value pair data type",
-  "version": "0.1.8",
-  "maintainers": [{ "name": "theory", "email": "[email protected]" }],
-  "license": "PostgreSQL",
-  "contents": {
-    "extensions": {
-      "pair": {
-        "sql": "sql/pair.sql",
-        "control": "pair.control"
-      }
-    }
-  },
-  "meta-spec": { "version": "2.0.0" }
-});
-
-let mut validator = Validator::new();
-assert!(validator.validate(&meta).is_ok());
-# Ok::<(), Box<dyn Error>>(())
-```
+This crate uses JSON Schema to validate and inspect the PGXN `META.json`
+files. It supports both the [v1] and [v2] specs.
 
 [v1]: https://rfcs.pgxn.org/0001-meta-spec-v1.html
-[v2]: https://rfcs.pgxn.org/0003-meta-spec-v2.html
+[v2]: https://github.com/pgxn/rfcs/pull/3
 
 */
 
-mod util;
-mod valid;
-pub use valid::{ValidationError, Validator};
-mod meta;
-// pub use meta::*;
+pub mod meta;
+mod util; // private utilities
+pub mod valid;
 
 #[cfg(test)]
 mod tests;

src/main.rs

@@ -7,7 +7,7 @@ use std::{
     process::ExitCode,
 };
 
-use pgxn_meta::Validator;
+use pgxn_meta::valid::Validator;
 use serde_json::Value;
 
 // Minimal main function; logical is all in run.

src/meta/mod.rs

@@ -1,3 +1,13 @@
+/*!
+PGXN Metadata management.
+
+This module provides interfaces to load, validate, and manipulate PGXN Meta
+Spec `META.json` files. It supports both the [v1] and [v2] specs.
+
+  [v1]: https://rfcs.pgxn.org/0001-meta-spec-v1.html
+  [v2]: https://github.com/pgxn/rfcs/pull/3
+
+*/
 use std::{collections::HashMap, error::Error, fs::File, path::PathBuf};
 
 use crate::util;
@@ -247,7 +257,9 @@ pub struct Artifact {
     sha512: Option<String>,
 }
 
-/// Represents a complete PGXN Meta definition.
+/**
+Represents a complete PGXN Meta definition.
+*/
 #[derive(Serialize, Deserialize, PartialEq, Debug)]
 pub struct Meta {
     name: String,
@@ -300,12 +312,13 @@ impl TryFrom<Value> for Meta {
 
 impl TryFrom<&[&Value]> for Meta {
     type Error = Box<dyn Error>;
-    // Merge multiple spec values into a single Meta object. The first value
-    // in `meta` should be the primary metadata, generally included in a
-    // distribution. Subsequent values will be merged into that first value
-    // via the [RFC 7396] merge pattern.
-    //
-    // [RFC 7396]: https://www.rfc-editor.org/rfc/rfc7396.html
+    /// Merge multiple spec values into a single Meta object.
+    ///
+    /// The first value in `meta` should be the primary metadata, generally
+    /// included in a distribution. Subsequent values will be merged into that
+    /// first value via the [RFC 7396] merge pattern.
+    ///
+    /// [RFC 7396]: https:///www.rfc-editor.org/rfc/rfc7396.html
     fn try_from(meta: &[&Value]) -> Result<Self, Self::Error> {
         if meta.is_empty() {
             return Err(Box::from("meta contains no values"));