diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index 70d9fc1..f33ca80 100644 --- a/DOCUMENTATION.md +++ b/DOCUMENTATION.md @@ -111,6 +111,55 @@ why, rather than widening the gate or silencing the lint crate-wide. There are currently six such allows, all `clippy::too_many_arguments` on SQL writers whose arguments are one-per-column. +`cargo check --workspace` is **not** a substitute for either of them. It does not +build `#[cfg(test)]` code, so a struct field removed from a type the tests +construct type-checks clean under `check` and fails under `test`/`--all-targets`. +That is exactly how `ac178ed` (drop the `icon` field) left `main` red: the commit +verified with `cargo check --workspace`, and the only remaining `icon` reference +was in `render_tests.rs`, which `check` never compiled. Use the two commands +above. + +### A green PR is not a green `main` + +Two PRs that are each green can still break `main` together — one removing a +field, the other adding a test that uses it. That is what happened here, and the +mechanism is worth knowing because the gate alone does not close it. + +CI *does* test the merge result, not the branch tip: on a `pull_request` event +`actions/checkout@v4` checks out `refs/pull/N/merge`. From the job log of the +run that validated this very fix: + +``` +git checkout --progress --force refs/remotes/pull/7/merge +HEAD is now at a679483 Merge a3d9fea... into f314846... +``` + +The catch is that this merge commit is a *snapshot*, recomputed when the PR +changes but not re-tested when `main` moves underneath it. PRs #3 and #4 both +declared base `6777b2c` and were merged twelve seconds apart; #4's green run had +been computed against a `main` that did not yet contain #3's new test file. No +job ever compiled the two together. + +Nothing stopped that merge because `main` has no branch protection +(`GET /repos/nusendra/ployer/branches/main/protection` → 404, "Branch not +protected"): no required status check, and no *Require branches to be up to date +before merging*, which is the setting that would have forced #4 to re-run +against the new base. Until that is enabled, the check is advisory. + +So: if your branch has been open across other merges, rebase onto `main` and +re-run the two commands above before merging. A green tick from a run that +predates the current `main` is not evidence about the `main` you are about to +create. + +Two further notes from the same incident, both still true: + +- `ci.yml` did not exist when #3 and #4 merged — it arrived eleven minutes later + in #6. The first run it ever did on `main` (push `f314846`) failed both jobs on + this exact error, and `main` stayed red for eighteen hours. A gate nobody reads + is not a gate. +- `--all-targets` is what makes clippy catch this class of break. The clippy job + failed here for the same reason the test job did. + `cargo fmt --check` is **not** a gate: the tree predates any formatting discipline and currently has ~325 unformatted hunks spread across nearly every file, so turning it on would either fail immediately or require a tree-wide diff --git a/crates/ployer-templates/src/render_tests.rs b/crates/ployer-templates/src/render_tests.rs index 65ff2f4..9c11e20 100644 --- a/crates/ployer-templates/src/render_tests.rs +++ b/crates/ployer-templates/src/render_tests.rs @@ -14,7 +14,6 @@ fn template_echoing(expr: &str) -> Template { name: "PostgreSQL".to_string(), description: String::new(), category: "database".to_string(), - icon: None, tags: Vec::new(), version: serde_json::Value::String("1.0.0".to_string()), inputs: Vec::new(), diff --git a/crates/ployer-templates/src/schema.rs b/crates/ployer-templates/src/schema.rs index c77787b..949cd3f 100644 --- a/crates/ployer-templates/src/schema.rs +++ b/crates/ployer-templates/src/schema.rs @@ -103,3 +103,7 @@ pub struct OutputItem { pub label: String, pub value: String, } + +#[cfg(test)] +#[path = "schema_tests.rs"] +mod tests; diff --git a/crates/ployer-templates/src/schema_tests.rs b/crates/ployer-templates/src/schema_tests.rs new file mode 100644 index 0000000..d911082 --- /dev/null +++ b/crates/ployer-templates/src/schema_tests.rs @@ -0,0 +1,75 @@ +use super::*; + +// --------------------------------------------------------------------------- +// Cross-repo compatibility: the removed `icon` key +// +// `icon` was dropped from `Template` and `IndexEntry` in ac178ed, but +// `ployer` (this binary) and `ployer-website` (which generates and serves the +// registry) deploy independently. The published catalog still ships the key on +// every entry, so the parser has to keep ignoring it. +// +// Verified against the live registry on 2026-10-29: +// +// $ curl -s https://ployer.nusendra.com/templates/index.json | grep -c '"icon"' +// 4 # jellyfin, mariadb, mongodb, postgresql +// $ curl -s https://ployer.nusendra.com/templates/postgresql.yaml | grep icon +// icon: postgresql.svg +// +// These two tests exist to fail loudly if anyone adds +// `#[serde(deny_unknown_fields)]` to either struct. That attribute looks like +// tightening; here it would make every install fail on a field nobody reads. +// --------------------------------------------------------------------------- + +/// The index is fetched before anything else, so a strict parser here breaks +/// the catalog listing outright — no template is installable. +#[test] +fn an_index_entry_carrying_the_removed_icon_key_still_parses() { + // Shape copied from the live index.json, trimmed to one entry. + let json = r#"{ + "schema_version": 1, + "generated_at": "2026-10-29T04:56:52.749Z", + "templates": [{ + "slug": "postgresql", + "name": "PostgreSQL", + "description": "Object-relational database with strong SQL standards compliance.", + "category": "database", + "icon": "postgresql.svg", + "tags": ["database", "sql", "postgres"], + "version": 1, + "sha256": "00", + "url": "https://ployer.nusendra.com/templates/postgresql.yaml" + }] + }"#; + + let index: RegistryIndex = + serde_json::from_str(json).expect("a stale `icon` key must not break index parsing"); + + assert_eq!(index.templates[0].slug, "postgresql"); + assert_eq!(index.templates[0].tags, ["database", "sql", "postgres"]); +} + +/// Same guarantee one level down: the template YAML served from the registry +/// still declares `icon:`, so `Template` must ignore it too. +#[test] +fn a_template_carrying_the_removed_icon_key_still_parses() { + // Shape copied from the live postgresql.yaml, trimmed to the required keys. + let yaml = r#" +slug: postgresql +name: PostgreSQL +description: Object-relational database with strong SQL standards compliance. +category: database +icon: postgresql.svg +tags: [database, sql, postgres] +version: 1 +compose: | + services: + postgresql: + image: postgres:17-alpine +"#; + + let t: Template = + serde_yaml::from_str(yaml).expect("a stale `icon:` must not break template parsing"); + + assert_eq!(t.slug, "postgresql"); + assert!(t.compose.contains("image: postgres:17-alpine")); +}