Skip to content

docs: README leads with the pitch, homepage snippet, a verified 60-second quickstart, and badges - #27

Draft
rgamba wants to merge 1 commit into
mainfrom
claude/readme-audit-restructure-f7cbd3
Draft

rgamba wants to merge 1 commit into
mainfrom
claude/readme-audit-restructure-f7cbd3

Conversation

@rgamba

@rgamba rgamba commented Sep 15, 2026

Copy link
Copy Markdown
Member

Summary

Restructures the README along the lines of the promotion audit: lead with the one-line pitch and the Kotlin hero snippet from the homepage, follow with a quickstart that is copy-pasteable end to end, and complete the badge row.

What changed

  • Above the fold. The pitch now matches the homepage (“Durable execution, embedded in your service”) and the first code block is the homepage's CheckoutWorkflow hero snippet, so the README and the site tell the same story.
  • 60-second quickstart. One bash block creates a Gradle project (settings.gradle.kts, build.gradle.kts, Main.kt) via heredocs and runs it. It uses the embedded in-memory SQLite default, the AllOpen plugin that Kotlin adopters need, and quiets engine logs so the output is just Hello, world!. The previous, richer signals/waitUntil example moves to its own section right after.
  • Badges. Added CI (CircleCI, main) and a Javadoc badge next to Maven Central and the license. Dropped the redundant docs and Jackson badges from the row; the Jackson compatibility note stays in the text.
  • Everything below the quickstart (how it works, production stores, capability table, fit, contributing) is kept, lightly reordered.

Trade-off: the Javadoc badge does not point at javadoc.io yet. javadoc.io resolves artifacts through the legacy search.maven.org index, which currently returns zero results for com.airbnb.skipper:skipper-core even though Central lists 0.8.0 and the Dokka javadoc jar is published. javadoc.io therefore renders javadoc: unknown and lands on an empty versions page. The badge links to the site's API reference instead; once the index catches up it can be repointed to https://javadoc.io/doc/com.airbnb.skipper/skipper-core in a one-line change.

Testing

  • Extracted the quickstart bash block from the README verbatim with awk and ran it in a clean directory against skipper-core:0.8.0 from Maven Central (Gradle 9.7.1 wrapper, JDK 21 host, toolchain 17). Output was exactly Hello, world!.
  • Confirmed the Kotlin factory<GreetingWorkflow>("id") operator and SkipperOpen annotation exist in skipper-core sources.
  • Verified the Maven Central, CircleCI (dl.circleci.com/status-badge/.../tree/main.svg, HTTP 200 SVG) and shields.io badge URLs resolve.
  • Docs-only change; no Kotlin/Java sources touched, so spotlessCheck is unaffected.

…verified 60-second quickstart, and CI/Javadoc badges

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant