Skip to content

docs: OpenSSF Best Practices passing-level artifacts #147

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bernardladenthin merged 1 commit into from
May 16, 2026
Merged

docs: OpenSSF Best Practices passing-level artifacts #147

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
37 changes: 37 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

---

## Release Process

@claude claude Bot May 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Format Issue: Per Keep a Changelog 1.1.0, the [Unreleased] section should be first after the header description. Consider moving this entire "Release Process" section to the bottom of the file (after the version history) to comply with the standard format. This also improves discoverability since users expect to see changes at the top.


> Paste this prompt into a new Claude Code session, fill in the three placeholders, and send it to perform a release.

```
Release `{PROJECT}` to Maven Central.

**Step 1 — Prepare the release (do immediately):**
1. Read the current version from `pom.xml` on `main` — it will be `{VERSION}-SNAPSHOT`
2. Strip `-SNAPSHOT` from `pom.xml` (→ `{VERSION}`)
3. In `README.md`, update **both**:
- The release dependency example to `{VERSION}`
- The snapshot dependency example to `{VERSION}-SNAPSHOT` (it should already match, but verify)
4. Commit both files directly to `main` (no pull request)

@claude claude Bot May 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Governance Note: Direct commits to main bypass code review and CI gates. While this may be intentional to avoid intermediate CI runs during version bumps, it should be documented with explicit security justification in a maintainer guide (e.g., SECURITY.md or a separate RELEASE.md). Consider adding: "Note: Direct commits to main are used here to avoid unnecessary CI runs on version-only changes. Maintainers must ensure the commit is reviewed and all prior CI checks on the development branch passed before this step."


@claude claude Bot May 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing Pre-Release Validation: The process should include an explicit step to verify all CI checks pass before tagging. Add after step 4:

Step 1.5 — Verify CI:

Wait for the publish workflow (GitHub Actions) to complete successfully for the version-bump commit. Verify that CodeQL, test coverage, and all build artifacts are green before proceeding to Step 2.

This prevents releasing with known CI failures.

**Step 2 — Wait for manual confirmation:**

@claude claude Bot May 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Governance Risk: This statement is ambiguous — it suggests an AI agent ("I") is performing tag/release creation, which is a significant security and governance concern.

Clarify as: "After CI confirms all checks pass, manually create the v{VERSION} tag and GitHub release (this requires maintainer credentials and should not be automated by AI agents)."

The release process template must make explicit that human maintainers, not AI systems, are responsible for creating tags and publishing to Maven Central.

I will create the `v{VERSION}` tag and GitHub release manually — wait for me to confirm
the release is published on Maven Central before proceeding.

**Step 3 — Post-release snapshot bump (after my confirmation):**
Bump **both** files on `main`:
- `pom.xml` → `{NEXT_VERSION}-SNAPSHOT`
- `README.md` snapshot dependency example → `{NEXT_VERSION}-SNAPSHOT`

Commit both changes together directly to `main`.

**Placeholders:**

| Placeholder | Value |
|------------------|----------------------------------------------|
| `{PROJECT}` | *(project name)* |
| `{VERSION}` | *(release version, e.g. `1.3.0`)* |

@claude claude Bot May 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Version Bump Guidance: The example shows a patch-level bump (1.3.0 → 1.3.1), but the process should explain how to choose the version when changes include features or breaking changes. Add a note:

| Semantic Version | When to use | Example |
|---|---|---|
| Major (X.0.0) | Breaking changes to API | 4.0.0 → 5.0.0 |
| Minor (X.Y.0) | New features, backward-compatible | 5.0.0 → 5.1.0 |
| Patch (X.Y.Z) | Bug fixes, internal changes | 5.0.0 → 5.0.1 |

Refer to semver.org for guidance on the next version choice.

| `{NEXT_VERSION}` | *(next snapshot base, e.g. `1.3.1`)* |
```

---

## [Unreleased]

### Added
Expand Down
Loading