From f6f1163d34174e7efe35eb6258806cfdbbacf97f Mon Sep 17 00:00:00 2001 From: Jonathan Ringer Date: Sun, 3 May 2026 22:34:33 -0700 Subject: [PATCH 1/2] Ekapkgs-update passthru support in Ekapkgs --- eeps/0039-ekapkgs-update-passthru.md | 117 +++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 eeps/0039-ekapkgs-update-passthru.md diff --git a/eeps/0039-ekapkgs-update-passthru.md b/eeps/0039-ekapkgs-update-passthru.md new file mode 100644 index 0000000..6deb8ab --- /dev/null +++ b/eeps/0039-ekapkgs-update-passthru.md @@ -0,0 +1,117 @@ +--- +EEP: 0039 +Title: Communicate ekapkgs-update policy through passthru +Author: Jonathan Ringer +Status: Draft +Type: Standards Track +Topic: Packaging +Created: 2026-05-03 +--- + +# Motivation + +Package maintainers often need fine-grained control over how automated update tools handle their packages. Some packages require pinned versions for stability, others need to filter out pre-release versions, and some may have custom version detection requirements. Currently, there is no standardized way to communicate these preferences to the ekapkgs update tool. + +This proposal introduces a `passthru.ekapkgs-update` attribute scope that allows package maintainers to declaratively specify update behavior directly in their package definitions. This approach: + +- Provides a clear, self-documenting way to communicate update intent +- Reduces maintenance burden by eliminating the need for external configuration files +- Aligns with similar patterns in the Nix ecosystem (e.g., nix-update) +- Enables package-specific update policies that travel with the package definition + +# Detailed Specification + +The `passthru.ekapkgs-update` attribute set accepts the following options: + +## `skip` (boolean) + +When set to `true`, instructs ekapkgs to skip attempting to update this package entirely. + +**Type:** `bool` +**Default:** `false` +**Use cases:** +- Packages with intentionally pinned versions +- Packages undergoing critical testing that shouldn't be updated automatically +- Deprecated packages that should remain frozen +- Packages which require a lot of bespoke fixes to make work + +## `version-regex` (string) + +A regular expression pattern that valid version strings must match. The update tool will only consider versions that match this pattern. + +**Type:** `string` (POSIX extended regular expression) +**Default:** `null` (no filtering) +**Use cases:** +- Filtering out beta, rc, or alpha releases (e.g., `"^[0-9]+\\.[0-9]+\\.[0-9]+$"`) +- Restricting to specific version branches (e.g., `"^2\\..*"` for v2.x only) +- Excluding versions with specific suffixes or prefixes + +## `version-type` (string) + +Specifies the version detection strategy to use when checking for updates. + +**Type:** `string` +**Default:** `null` (auto-detect) +**Supported values:** +- `"stable"` - Only consider stable releases (default) +- `"unstable"` - Include pre-release versions +- `"branch"` - Track a specific branch +- `"commit"` - Track specific commits. Questionable value, `skip` may be more appropriate +- Custom values as supported by the update tool implementation + +**Use cases:** +- Packages that track unstable/development versions +- Packages that follow a specific branch rather than tags +- Packages with non-standard versioning schemes + +## `branch` (string) + +Specifies the branch to follow. Useful for maintenance branches. Only supported for some fetchers. + +**Type:** `string` +**Default:** `null` (auto-detect) + +**Use cases:** +- Maintenance branches which receive backports + + +# Example Usage + + +```nix +{ + + # Skip updates for a pinned package + passthru.ekapkgs-update.skip = true; + + # Filter out pre-release versions + passthru.ekapkgs-update = { + version-regex = "^[0-9]+\\.[0-9]+\\.[0-9]+$"; + }; + + # Track only v2.x releases + passthru.ekapkgs-update = { + version-regex = "^2\\..*"; + }; + + # Allow for prereleses. E.g. "0.1.0-alpha.5"; + passthru.ekapkgs-update = { + version-type = "unstable"; + }; + + # Pin to a version range, but allow unstable tags + passthru.ekapkgs-update = { + version-regex = "^1\\.[0-9]+\\.[0-9]+$"; + version-type = "stable"; + }; + +} +``` + +# Still questionable features + +- **`commit-message-template` (string)** - Custom commit message format + +# Future work + +- Implementation into [ekapkgs-update](https://github.com/ekala-project/ekapkgs-update/) From 94400e02c2edb7ea1f869d38175e4ede51c3cbb7 Mon Sep 17 00:00:00 2001 From: Jonathan Ringer Date: Sat, 9 May 2026 13:35:58 -0700 Subject: [PATCH 2/2] Drop version-type for semver options --- eeps/0039-ekapkgs-update-passthru.md | 65 ++++++++++++++++++---------- 1 file changed, 41 insertions(+), 24 deletions(-) diff --git a/eeps/0039-ekapkgs-update-passthru.md b/eeps/0039-ekapkgs-update-passthru.md index 6deb8ab..3dd23c6 100644 --- a/eeps/0039-ekapkgs-update-passthru.md +++ b/eeps/0039-ekapkgs-update-passthru.md @@ -46,33 +46,36 @@ A regular expression pattern that valid version strings must match. The update t - Restricting to specific version branches (e.g., `"^2\\..*"` for v2.x only) - Excluding versions with specific suffixes or prefixes -## `version-type` (string) +## `semver-strategy` (string) -Specifies the version detection strategy to use when checking for updates. +Controls which version updates are acceptable based on semantic versioning constraints. **Type:** `string` -**Default:** `null` (auto-detect) +**Default:** `"latest"` (accept any newer non-prerelease version) **Supported values:** -- `"stable"` - Only consider stable releases (default) -- `"unstable"` - Include pre-release versions -- `"branch"` - Track a specific branch -- `"commit"` - Track specific commits. Questionable value, `skip` may be more appropriate -- Custom values as supported by the update tool implementation +- `"latest"` - Accept any newer non-prerelease version (default) +- `"major"` - Same as "latest" - allow major version updates +- `"minor"` - Only update to latest minor version within the same major version (e.g., 1.x.x) +- `"patch"` - Only update to latest patch version within the same major.minor version (e.g., 1.2.x) **Use cases:** -- Packages that track unstable/development versions -- Packages that follow a specific branch rather than tags +- Conservative updates: Use `"patch"` to minimize breaking changes +- Moderate updates: Use `"minor"` to get new features without major version jumps - Packages with non-standard versioning schemes -## `branch` (string) +**Note:** Maps to the existing `SemverStrategy` enum in ekapkgs-update. -Specifies the branch to follow. Useful for maintenance branches. Only supported for some fetchers. +## `include-prereleases` (boolean) -**Type:** `string` -**Default:** `null` (auto-detect) +When set to `true`, allows the update tool to consider pre-release versions (alpha, beta, rc, etc.) as valid update candidates. + +**Type:** `bool` +**Default:** `false` (exclude prereleases) **Use cases:** -- Maintenance branches which receive backports +- Packages that track unstable/development versions +- Tracking development versions (e.g., Rust nightly, beta channels) +- Early adopters who want to test upcoming versions # Example Usage @@ -94,24 +97,38 @@ Specifies the branch to follow. Useful for maintenance branches. Only supported version-regex = "^2\\..*"; }; - # Allow for prereleses. E.g. "0.1.0-alpha.5"; + # Allow for prereleases. E.g. "0.1.0-alpha.5"; passthru.ekapkgs-update = { - version-type = "unstable"; + include-prereleases = true; }; - # Pin to a version range, but allow unstable tags + # Only accept patch updates within current version passthru.ekapkgs-update = { - version-regex = "^1\\.[0-9]+\\.[0-9]+$"; - version-type = "stable"; + semver-strategy = "patch"; + }; + + # Track minor versions, including prereleases + passthru.ekapkgs-update = { + semver-strategy = "minor"; + include-prereleases = true; }; } ``` -# Still questionable features +# Future work -- **`commit-message-template` (string)** - Custom commit message format +## Branch Tracking -# Future work +Tracking specific Git branches (e.g., `stable`, `lts-v2`) is deferred to future work as it requires a fundamentally different update mechanism than release/tag-based updates. Proposed attribute: + +```nix +passthru.ekapkgs-update = { + follow-branch = "stable"; # Track specific branch instead of releases +}; +``` -- Implementation into [ekapkgs-update](https://github.com/ekala-project/ekapkgs-update/) +**Challenges:** +- Branches don't have inherent version numbers +- Requires different API calls (branches endpoint vs releases/tags) +- Version comparison would need to use commit metadata instead of semver