ci: prevent SNAPSHOT releases; bump to 0.1.6-SNAPSHOT#49
ci: prevent SNAPSHOT releases; bump to 0.1.6-SNAPSHOT#49WilliamAGH wants to merge 5 commits intomainfrom
Conversation
When triggered by release:published events, GitHub Actions checks out the release tag (detached HEAD) rather than a branch. This caused git push to fail with "You are not currently on a branch" error. Fixed by explicitly specifying ref: main in the checkout step, ensuring the workflow always operates on the main branch regardless of trigger.
The repository’s agent guidance needed to be more explicit and linkable, with stable rule hashes that can be cited during reviews and automated changes. This formalizes additional non-negotiables (verification, SRP, LOC ceilings, dependency source inspection) and adds a single “code change contract” so new work follows consistent placement and splitting decisions. - Expand AGENTS rule summary and add missing rule sections/hashes - Add dependency source verification workflow (Gradle cache / sources JAR) - Add LOC ceiling and no-monolith decision rules (new file vs edit) - Add a contracts doc with a decision matrix and verification gates
Docs pages currently lack frontmatter metadata and there is no Mintlify docs configuration to define navigation and site identity. This adds the Mintlify `docs.json` plus per-page titles so the documentation can be rendered and navigated consistently. - Add docs/docs.json with theme, name, and grouped navigation - Add YAML frontmatter titles to core docs pages - Include Contracts navigation entry pointing at the code-change contract page
📝 WalkthroughWalkthroughThis pull request adds snapshot release handling and stricter release gating: CI now detects SNAPSHOT versions via an Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant Dev as Developer (push/tag)
participant GH as GitHub Actions
participant Gradle as Gradle build
participant Repo as Artifact Repo (Sonatype)
Dev->>GH: push to main / create release
GH->>Gradle: read `VERSION_NAME` (via workflow output)
GH->>GH: set `is_snapshot` output (true/false)
alt is_snapshot == true
GH->>Gradle: run publish (snapshot)
Gradle->>Repo: publish `*-SNAPSHOT`
else is_snapshot == false
GH->>GH: Release flow continues
GH->>Gradle: build & test, then publish release
Gradle->>Repo: publish release artifact
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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. Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3134895ba2
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| } | ||
|
|
||
| dependencies { | ||
| implementation("com.williamcallahan:apple-maps-java:0.1.6-SNAPSHOT") |
There was a problem hiding this comment.
Adding this -SNAPSHOT dependency example introduces a regression with the existing UpdateReadmeVersion workflow: its global regex replacement updates every implementation("com.williamcallahan:apple-maps-java:...") occurrence, so the next scheduled/release run will overwrite this snapshot line to the latest release version and break the snapshot instructions. Scope the replacement to the release-install snippet (or explicitly exclude the snapshot block) so docs stay correct after automation runs.
Useful? React with 👍 / 👎.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @.github/workflows/CI.yaml:
- Around line 32-41: The version_check step currently sets VERSION from
gradle.properties but will silently treat a missing or empty VERSION_NAME as
non-snapshot; modify the run block for the step with id version_check to enable
strict shell mode (set -euo pipefail) and add an explicit non-empty check for
VERSION (e.g., if [ -z "$VERSION" ]; then echo "ERROR: VERSION_NAME not found or
empty" >&2; exit 1; fi) before the SNAPSHOT test, so the job fails fast and
loudly when VERSION_NAME is absent.
| - name: Check if SNAPSHOT version | ||
| id: version_check | ||
| run: | | ||
| VERSION=$(grep '^VERSION_NAME=' gradle.properties | cut -d'=' -f2) | ||
| echo "VERSION=${VERSION}-SNAPSHOT" >> $GITHUB_OUTPUT | ||
| echo "Version: $VERSION" | ||
| if [[ "$VERSION" == *-SNAPSHOT ]]; then | ||
| echo "is_snapshot=true" >> $GITHUB_OUTPUT | ||
| else | ||
| echo "is_snapshot=false" >> $GITHUB_OUTPUT | ||
| fi |
There was a problem hiding this comment.
Guard against missing VERSION_NAME to avoid silent skips.
If VERSION_NAME is absent or empty, this step will quietly set is_snapshot=false and skip snapshot publishing. Adding strict mode + a non-empty check makes the failure loud and easy to debug. Tiny CI hygiene win. 🌱
✅ Suggested hardening
- name: Check if SNAPSHOT version
id: version_check
+ shell: bash
run: |
- VERSION=$(grep '^VERSION_NAME=' gradle.properties | cut -d'=' -f2)
+ set -euo pipefail
+ VERSION=$(grep -E '^VERSION_NAME=' gradle.properties | head -n1 | cut -d'=' -f2 | tr -d '\r')
+ if [[ -z "$VERSION" ]]; then
+ echo "::error::VERSION_NAME not found in gradle.properties"
+ exit 1
+ fi
echo "Version: $VERSION"
if [[ "$VERSION" == *-SNAPSHOT ]]; then
- echo "is_snapshot=true" >> $GITHUB_OUTPUT
+ echo "is_snapshot=true" >> "$GITHUB_OUTPUT"
else
- echo "is_snapshot=false" >> $GITHUB_OUTPUT
+ echo "is_snapshot=false" >> "$GITHUB_OUTPUT"
fi🤖 Prompt for AI Agents
In @.github/workflows/CI.yaml around lines 32 - 41, The version_check step
currently sets VERSION from gradle.properties but will silently treat a missing
or empty VERSION_NAME as non-snapshot; modify the run block for the step with id
version_check to enable strict shell mode (set -euo pipefail) and add an
explicit non-empty check for VERSION (e.g., if [ -z "$VERSION" ]; then echo
"ERROR: VERSION_NAME not found or empty" >&2; exit 1; fi) before the SNAPSHOT
test, so the job fails fast and loudly when VERSION_NAME is absent.
…ndency - Add Mintlify docs badge to badge row - Add version callout with Maven Central and mvnrepository links - Add Maven <dependency> element to snapshot XML section - Clarify snapshots are auto-published on every push to main
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| implementation("com.williamcallahan:apple-maps-java:0.1.6-SNAPSHOT") | ||
| } | ||
| ``` | ||
|
|
||
| Maven: | ||
|
|
||
| ```xml | ||
| <repositories> | ||
| <repository> | ||
| <id>sonatype-snapshots</id> | ||
| <url>https://central.sonatype.com/repository/maven-snapshots/</url> | ||
| <releases> | ||
| <enabled>false</enabled> | ||
| </releases> | ||
| <snapshots> | ||
| <enabled>true</enabled> | ||
| </snapshots> | ||
| </repository> | ||
| </repositories> | ||
|
|
||
| <dependencies> | ||
| <dependency> | ||
| <groupId>com.williamcallahan</groupId> | ||
| <artifactId>apple-maps-java</artifactId> | ||
| <version>0.1.6-SNAPSHOT</version> | ||
| </dependency> |
There was a problem hiding this comment.
UpdateReadmeVersion will overwrite snapshot coordinates with the stable version
The UpdateReadmeVersion.yaml perl substitutions use the /g (global) flag, so they match all occurrences of the dependency coordinates in the file — including the new snapshot section. The next time that workflow runs (daily schedule, or on the next release), it will replace 0.1.6-SNAPSHOT in both the Gradle and Maven snapshot snippets with the latest Maven Central stable version (e.g., 0.1.5), silently corrupting the documentation for consumers who rely on snapshots.
The simplest fix is to guard the regex so it only touches non-SNAPSHOT versions:
# Gradle snippet — stable only
s/(implementation\("com\.williamcallahan:apple-maps-java:)(?!.*SNAPSHOT)[^"]+("\))/$1$v$2/g;
# Maven snippet — stable only
s#(<dependency>\s*<groupId>com\.williamcallahan</groupId>\s*<artifactId>apple-maps-java</artifactId>\s*<version>)(?!.*SNAPSHOT)[^<]+(</version>\s*</dependency>)#$1$v$2#gms;Alternatively, wrap each stable snippet in HTML comment markers and scope the replacement to only that region.
Prompt To Fix With AI
This is a comment left during a code review.
Path: README.md
Line: 77-102
Comment:
**`UpdateReadmeVersion` will overwrite snapshot coordinates with the stable version**
The `UpdateReadmeVersion.yaml` perl substitutions use the `/g` (global) flag, so they match **all** occurrences of the dependency coordinates in the file — including the new snapshot section. The next time that workflow runs (daily schedule, or on the next release), it will replace `0.1.6-SNAPSHOT` in both the Gradle and Maven snapshot snippets with the latest Maven Central stable version (e.g., `0.1.5`), silently corrupting the documentation for consumers who rely on snapshots.
The simplest fix is to guard the regex so it only touches non-SNAPSHOT versions:
```perl
# Gradle snippet — stable only
s/(implementation\("com\.williamcallahan:apple-maps-java:)(?!.*SNAPSHOT)[^"]+("\))/$1$v$2/g;
# Maven snippet — stable only
s#(<dependency>\s*<groupId>com\.williamcallahan</groupId>\s*<artifactId>apple-maps-java</artifactId>\s*<version>)(?!.*SNAPSHOT)[^<]+(</version>\s*</dependency>)#$1$v$2#gms;
```
Alternatively, wrap each stable snippet in HTML comment markers and scope the replacement to only that region.
How can I resolve this? If you propose a fix, please make it concise.
There was a problem hiding this comment.
Pull request overview
Updates CI/release guardrails to prevent accidental SNAPSHOT releases to Maven Central, bumps the project to the next snapshot version, and adds snapshot consumption + Mintlify docs metadata.
Changes:
- Add workflow checks to block publishing SNAPSHOTs via the release workflow and only publish snapshots from
mainwhenVERSION_NAMEends with-SNAPSHOT. - Bump
VERSION_NAMEto0.1.6-SNAPSHOTand document snapshot repository/dependency coordinates in the README. - Introduce Mintlify docs configuration (
docs.json) and add front matter to existing docs pages.
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| README.md | Adds docs badge, stable release pointer, and snapshot repository/dependency instructions. |
| gradle.properties | Bumps VERSION_NAME to 0.1.6-SNAPSHOT. |
| docs/usage.md | Adds Mintlify front matter metadata. |
| docs/tests.md | Adds Mintlify front matter metadata. |
| docs/docs.json | Adds Mintlify documentation site configuration and navigation. |
| docs/contracts/code-change.md | Adds a “code change policy contract” doc page. |
| docs/cli.md | Adds Mintlify front matter metadata. |
| docs/authorization.md | Adds Mintlify front matter metadata. |
| AGENTS.md | Expands and reorganizes agent rules (zero-tolerance, git permissions, architecture, etc.). |
| .github/workflows/UpdateReadmeVersion.yaml | Ensures README updates are performed against main instead of a release ref. |
| .github/workflows/Release.yaml | Fails fast when the release tag resolves to a -SNAPSHOT version. |
| .github/workflows/CI.yaml | Publishes snapshots only when VERSION_NAME is a -SNAPSHOT and avoids overriding -Pversion. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| ## Installation | ||
|
|
||
| > Latest stable release: **0.1.5** — [view on Maven Central](https://central.sonatype.com/artifact/com.williamcallahan/apple-maps-java) | [view on mvnrepository](https://mvnrepository.com/artifact/com.williamcallahan/apple-maps-java) |
There was a problem hiding this comment.
The README now hardcodes the latest stable release version ("Latest stable release: 0.1.5"), but the UpdateReadmeVersion workflow only rewrites the dependency snippet versions. This line will drift after the next release unless the workflow is updated to rewrite it too (or the line is removed in favor of the Central link alone).
| > Latest stable release: **0.1.5** — [view on Maven Central](https://central.sonatype.com/artifact/com.williamcallahan/apple-maps-java) | [view on mvnrepository](https://mvnrepository.com/artifact/com.williamcallahan/apple-maps-java) | |
| > View the latest release on [Maven Central](https://central.sonatype.com/artifact/com.williamcallahan/apple-maps-java) | [mvnrepository](https://mvnrepository.com/artifact/com.williamcallahan/apple-maps-java) |
Mirrors the Maven Central publishing guardrails used in tui4j.
Changes:
Verification:
Greptile Summary
This PR adds guardrails to prevent SNAPSHOT versions from being published to Maven Central, bumps
VERSION_NAMEto0.1.6-SNAPSHOT, and documents the Sonatype snapshot repository in the README. The CI and Release workflow changes are clean and correct.README.mdcontainsimplementation(\"com.williamcallahan:apple-maps-java:0.1.6-SNAPSHOT\")and the matching Maven<version>0.1.6-SNAPSHOT</version>. The pre-existingUpdateReadmeVersion.yamlperl substitutions use the/gflag and will replace all matching coordinates globally — including those in the snapshot section — with the latest stable version from Maven Central on its next run (daily schedule or next release trigger). TheUpdateReadmeVersionscript needs its regexes scoped to non-SNAPSHOT versions before this README section can be trusted.Confidence Score: 4/5
Safe to merge after fixing the UpdateReadmeVersion regex scope, which will otherwise silently corrupt the new snapshot docs on its next run.
All CI/workflow logic changes are correct and well-structured. The sole P1 finding is in README.md: the existing global regex in UpdateReadmeVersion.yaml will overwrite the new snapshot coordinates with the stable release version, breaking the snapshot documentation for consumers.
README.md (snapshot section) and .github/workflows/UpdateReadmeVersion.yaml (perl regex scope)
Important Files Changed
Flowchart
%%{init: {'theme': 'neutral'}}%% flowchart TD A[Push to main] --> B{version_check:\nVERSION_NAME ends\nwith -SNAPSHOT?} B -- Yes --> C[Publish SNAPSHOT\npublishAllPublicationsToCentralPortalSnapshots] B -- No --> D[Skip publish] E[GitHub Release published] --> F[Extract version\nfrom tag] F --> G{Fail if SNAPSHOT tag:\nVERSION ends with\n-SNAPSHOT?} G -- Yes --> H[Exit 1\nRefuse SNAPSHOT release] G -- No --> I[Build & Test\n-Pversion=TAG] I --> J[Deploy to Maven Central\npublishAllPublicationsToCentralPortal] K[Daily schedule / release trigger] --> L[UpdateReadmeVersion:\nFetch latest stable\nfrom Maven Central] L --> M{Resolved version\nis SNAPSHOT?} M -- Yes --> N[Exit 1\nRefuse SNAPSHOT update] M -- No --> O[Perl regex /g:\nupdates ALL coords\nincl. snapshot section]Prompt To Fix All With AI
Reviews (1): Last reviewed commit: "docs: add Mintlify badge, mvnrepository ..." | Re-trigger Greptile