Skip to content

build: document releases and adopt Changie - #268

Draft
ffumero2003 wants to merge 15 commits into
masterfrom
release-standard-conformance
Draft

ffumero2003 wants to merge 15 commits into
masterfrom
release-standard-conformance

Conversation

@ffumero2003

@ffumero2003 ffumero2003 commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Context

Release preparation needs a reproducible changelog and a documented path from version selection to Maven Central verification.

Changes

  • Add RELEASE.md with release milestones, Changie/version updates, build and local health-check commands, signed tagging, deployment, verification, and recovery steps.
  • Migrate 20 published changelog sections and five unreleased entries to Changie without rewriting the published notes. New PRs add fragments; batching updates the changelog and gradle.properties together.
  • Add the changelog-check CI job and tests for release-note extraction and changelog/version consistency.

This is the first of two stacked changes. Deployment controls and automated release notes follow in #269; the runbook documents the validated manual notes update for releases made before that automation is enabled. Maven Central publication, artifact signing, and Sonatype staging configuration are unchanged.

Before the first release, the release owner must approve and document the Maven artifact-signing public-key source, full primary fingerprint, and independent confirmation procedure. RELEASE.md records this prerequisite as a TODO; no production signing fingerprint is approved here.

Release gates and workflow wiring land in the stacked follow-up #269; merge #268 before #269.

Verification

  • ./gradlew build --no-daemon passed.
  • Thirty-two release metadata/Changie tests passed, including a real disposable batch/merge, generated-file checks, a narrow Dependabot workflow-update exemption, independent version/notes consistency checks, verification of POM/main/sources/Javadoc signatures for all four published modules, download/signature failure guards and configured primary-fingerprint checks across multiple fixture identities, new-fragment enforcement, preservation of all five migrated entries through batching, tag commands in a fresh shell with only TAG exported and metadata/ancestry/version guards that stop before tag creation and signature-verification failures that delete the newly created local tag and stop before pushing, explicit simulator-URL propagation to the health harness, and a validated manual release-notes update with cleanup on success and failure.
  • A disposable real-GPG smoke check verified all 16 POM/JAR artifacts using the configured primary fingerprint and rejected a subkey configured as the primary, an unexpected signer, and an altered JAR after its valid POM.
  • All 11 changelog tests also passed against a disposable post-batch release-prep checkout where migrated YAML fragments had been consumed and the version notes were retained.
  • A real Git/SSH check accepted the trusted fixture key and confirmed that failed SSH verification deletes the newly created local tag.
  • A real Gradle-backed test invokes :b2-sdk-httpclient:healthClasspath and resolves the documented runtime classpath, and a missing-task mutation fails. A real Git/Changie test accepts a valid batch even when Git detects its fragment as a rename into version notes; renaming an existing fragment is rejected as a substitute for a new entry.
  • The documented local health check returned SDKHARNESS_RESULT health golden-path PASS - against a disposable loopback simulator.
  • The publishing task graph passed with --dry-run and placeholder credentials; signing, publishing, and staging close/release tasks were skipped. This does not validate production credentials or publish artifacts.
  • actionlint passed for the new changelog workflow; published changelog sections were checked against the originals.

Closes #266

@ffumero2003

Copy link
Copy Markdown
Contributor Author

Snyk Code (code/snyk) — 6 findings triaged as false positives

The SAST check reports 6 newly introduced issues in the release tooling (scripts/release.py, scripts/tests/test_release.py). All six are false positives in this context:

  • Command Injection (CWE-78) ×3 — release.py:45, release.py:51, test_release.py:137. These subprocess.run calls use list-form arguments with no shell=True; the flagged "environment variable" is the Changie executable path (e.g. [changie, "merge"]), not a shell string. With no shell there is no command string to inject — the env var only selects which trusted binary to invoke.
  • Path Traversal (CWE-23) ×3 — release.py:42-48 (shutil.copy / copytree). The flagged input is a maintainer-supplied command-line argument to a local release script run by maintainers and CI, not untrusted external input crossing a trust boundary.

These are local release/test scripts executed by trusted operators and CI with trusted inputs; none of the flagged flows is an untrusted trust boundary. code/snyk is not a required status check on this repository, so it does not gate merge. The findings are being dismissed in Snyk as false positives with this rationale.

Require an added fragment for ordinary changes and preserve release-preparation handling. Pin the five migrated entries through Changie batching and merging. Make the documented tag block stop on failed metadata, ancestry, version, or signature checks, with focused regression tests.
Stop the verification block on download or signature failures and require the independently confirmed artifact-signing fingerprint. Check primary-key and signing-subkey status records, with regression coverage for failed downloads, invalid signatures, and unexpected signers.
Leave the artifact-signing key source and independent confirmation procedure for release-owner approval. Require the configured primary fingerprint and cover multiple fixture identities, signing subkeys, and rejection of a subkey configured as the primary key.
Verify main, sources, and Javadoc JAR signatures alongside each POM. Exercise failures in JAR downloads and signatures even when POM verification succeeds. Run the standalone tag example test with only its required environment.
Delete a newly created local tag if signature verification fails, and explicitly pass the simulator URL to the health harness. Cover both failure paths with shell contract tests.
Mirror the local tag cleanup guard in the documented SSH signing alternative. Verify trusted and rejected signatures with real disposable Git and SSH keys, including execution of tag deletion after rejection.
Disable rename detection when validating release-preparation changes so a fragment batched into version notes is counted as a new notes file. Add a real Git and Changie regression for that case.\n\nExercise the documented runtime classpath task through Gradle and provision Java for the changelog test job.
Use rename-aware statuses for the new-entry requirement, independent of user Git configuration. Disable rename detection only when recognizing batched version notes in a release-preparation diff.

Cover both accepted release batching and rejection of a renamed existing fragment with real Git and Changie.
@ffumero2003
ffumero2003 enabled auto-merge (squash) November 19, 2026 16:24
@ffumero2003
ffumero2003 disabled auto-merge November 19, 2026 16:24
@ffumero2003
ffumero2003 marked this pull request as draft November 19, 2026 16:30
@ffumero2003

Copy link
Copy Markdown
Contributor Author

Converting to draft and parking this. The release-process standardization for this repo is on hold pending internal coordination on ownership; the branch, commits and green panel results are preserved to revisit later. Not for merge in the meantime.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document and automate release preparation with Changie

1 participant