ci: stamp file_description with CS release + compat matrix

[alandtse]

A common complaint on Nexus comments after every CS release is which feature versions go with this Community Shaders version? Today, every uploaded .7z carries the upstream-default file description "See mod description for details." — which doesn't actually help the user match versions.

This PR replaces that default with version-anchored content, populated by the audit tool from the same INI metadata it already reads.

What users will see

Core (Community Shaders) file row:

Community Shaders 1.5.2 — feature versions in this release:
• Cloud Shadows 1.4.0
• Grass Collision 3.0.4
• Grass Lighting 2.0.2
• Hair Specular 1.1.0 (unchanged)
• HDR 1.0.1
• Screen Space GI 4.1.0 (unchanged)
• Screen Space Shadows 2.1.0 (unchanged)
• Sky Sync 1.1.0 (unchanged)
• Skylighting 1.3.0 (unchanged)
• Subsurface Scattering 3.0.2 (unchanged)
• Terrain Blending 1.1.0 (unchanged)
• Terrain Helper 1.0.0 (unchanged)
• Terrain Variation 1.0.1 (unchanged)
• Upscaling 1.4.0
• Wetness Effects 3.1.0 (unchanged)

(Sample output from python tools/feature_version_audit.py --export-nexus-matrix --base v1.5.1 --release-version 1.5.2 --all-features.)

The (unchanged) annotation appears when the feature's Version in its .ini matches the same .ini at the previous stable tag — so users can see at a glance which features actually moved versus which carried over.

Each feature file row:

Cloud Shadows 1.4.0 — released for Community Shaders 1.5.2.

Anchors each .7z to the CS release it shipped with. Answers the inverse question ("which CS does this Cloud Shadows file go with?") right on the file row.

Why no forward-looking ranges

Considered making this a range (e.g., Cloud Shadows 1.4.0 — released for CS 1.5.2 to 1.5.4). Decided against it:

1. The forward end isn't knowable at upload time. When CS 1.5.3 next ships and Cloud Shadows hasn't bumped, the "real" range becomes 1.5.2 to 1.5.3 — but the upload action uses check_existing: true and skips the upload, so the file row's description never gets revisited.
2. Maintaining a forward range would need a separate "refresh descriptions" workflow that runs after each CS release and updates already-uploaded file descriptions in place. Doable later (unex supports this independently of file upload), but extra surface and not needed for the v1 ask.
3. Single-version stamp is accurate forever and never lies. If we add range maintenance later, it's purely additive — no rework.

Implementation

tools/feature_version_audit.py:

• New --release-version CLI arg (e.g. 1.5.2).
• build_nexus_upload_matrix accepts release_version=.... When provided, populates a file_description field on every row. New helper _build_compat_bullets walks the same metadata used elsewhere in the file, marks rows as (unchanged) using the existing get_prior_version helper against --base.
• When --release-version is omitted (e.g. ad-hoc manual dispatches without a built-from-tag context), file_description is empty and the upstream Nexus action default is preserved — backward compatible.

.github/workflows/nexus-upload.yaml:

• Passes --release-version "$RELEASE_VER" (the release tag with the leading v stripped) to the audit tool.
• Forwards matrix.file_description into alandtse/nexus-workflows/upload-nexus.yml's existing file_description input.

What this does NOT do

• Does not change the per-feature changelog (still derived from commits since base).
• Does not change the GitHub release body (still semantic-release output).
• Does not revisit already-uploaded file descriptions on Nexus.
• Does not introduce range tracking — see "Why no forward-looking ranges" above.

Stacking

Independent of #2350 (artifact-pattern overrides + missing-artifact warning). They can land in either order.

Summary by CodeRabbit

Release Notes

• Chores
  • Enhanced release package descriptions on Nexus to include version information and feature compatibility details, providing clearer visibility when browsing available releases.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds support for embedding Nexus upload file descriptions anchored to a specific Community Shaders release version. A new --release-version CLI parameter drives compatibility bullet generation in the matrix export, which flows through the workflow to populate descriptions in the final Nexus upload call.

Changes

Nexus file description generation from release version

Layer / File(s)	Summary
CLI release-version argument tools/feature_version_audit.py	Adds --release-version CLI argument to optionally anchor Nexus matrix file descriptions to a specific Community Shaders release version.
Matrix file description generation tools/feature_version_audit.py	Introduces helper function to generate compatibility bullet strings for auto-upload Nexus features (annotating versions as unchanged relative to base_ref). Updates build_nexus_upload_matrix() to accept release_version parameter and populate core row file_description from compatibility bullets; populates per-feature file_description for non-core rows when both release version and feature version are known.
CLI to matrix function wiring tools/feature_version_audit.py	Passes args.release_version into build_nexus_upload_matrix() during --export-nexus-matrix execution.
Workflow release version extraction and upload integration .github/workflows/nexus-upload.yaml, tools/feature_version_audit.py	Workflow derives normalized release version by stripping leading v from RELEASE_TAG and appends --release-version to audit tool invocation. Adds file_description input to upload-to-nexus reusable workflow call using matrix.file_description with empty-string fallback.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• community-shaders/skyrim-community-shaders#2256: Both PRs modify build_nexus_upload_matrix() to enhance Nexus matrix row construction (this PR adds release_version-driven file_description, that PR changes artifact/changelog resolution).
• community-shaders/skyrim-community-shaders#2254: Both PRs wire release-specific text generation into the Nexus matrix export and workflow (this PR: file_description from --release-version and compatibility bullets; that PR: changelog from base_ref and git-log).

Suggested reviewers

• doodlum
• SkrubbySkrubInAShrub
• davo0411

Poem

🐰 A version tag arrives, stripped clean and bright,
Through audit tools it flows, describing each feature's flight,
Bullets dance in matrices, marking what's unchanged with care,
Nexus gets its file descriptions, release wisdom everywhere!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: stamping file descriptions with Community Shaders release and compatibility matrix information for Nexus uploads.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

.github/workflows/nexus-upload.yaml (1)

1-1: ⚡ Quick win

Consider shortening the PR title to meet the 50-character guideline.

The current title "ci(nexus): stamp file_description with CS release + compat matrix" is 66 characters, exceeding the conventional commit 50-character recommendation. Consider shortening to improve readability:

• ci(nexus): add release-stamped file descriptions (48 chars)
• ci(nexus): stamp file_description with release (47 chars)

As per coding guidelines, conventional commit titles should stay within 50 characters for the type(scope): description format.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/nexus-upload.yaml at line 1, The PR title exceeds the
50-character conventional-commit guideline ("ci(nexus): stamp file_description
with CS release + compat matrix"); shorten it to <=50 characters using the
type(scope): description format (for example "ci(nexus): add release-stamped
file descriptions" or "ci(nexus): stamp file_description with release") and
update the PR title accordingly so it conforms to the conventional commit length
rule.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In @.github/workflows/nexus-upload.yaml:
- Line 1: The PR title exceeds the 50-character conventional-commit guideline
("ci(nexus): stamp file_description with CS release + compat matrix"); shorten
it to <=50 characters using the type(scope): description format (for example
"ci(nexus): add release-stamped file descriptions" or "ci(nexus): stamp
file_description with release") and update the PR title accordingly so it
conforms to the conventional commit length rule.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 6a71cb04-1267-4d6b-a89e-a898927e6c36

📥 Commits

Reviewing files that changed from the base of the PR and between be27598 and a91b6c1.

📒 Files selected for processing (2)

• .github/workflows/nexus-upload.yaml
• tools/feature_version_audit.py