Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
49 changes: 49 additions & 0 deletions DOCUMENTATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 0 additions & 1 deletion crates/ployer-templates/src/render_tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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(),
Expand Down
4 changes: 4 additions & 0 deletions crates/ployer-templates/src/schema.rs
Original file line number Diff line number Diff line change
Expand Up @@ -103,3 +103,7 @@ pub struct OutputItem {
pub label: String,
pub value: String,
}

#[cfg(test)]
#[path = "schema_tests.rs"]
mod tests;
75 changes: 75 additions & 0 deletions crates/ployer-templates/src/schema_tests.rs
Original file line number Diff line number Diff line change
@@ -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"));
}
Loading