Release requirements
The changelog, hero screenshot and tags every release needs, and how they're checked.
Coding agents: read this page as markdown.
Every release on releaseszn needs a tagged GitHub release, a real changelog
and a hero screenshot that passes a quality check. The checks run when you
publish, and you can run them earlier with
POST …/check.
Tagged GitHub release #
Releases are imported from your repository’s GitHub releases. You can’t create a release on releaseszn that doesn’t exist on GitHub, so nobody can publish a version you didn’t ship.
Two tag names can’t be releases, because they are pages of every project:
stats and feed.xml. A release tagged exactly that is skipped on import,
and the project’s import_error says so. Tag it like a version (v1.0.0)
instead.
Changelog #
Say what changed and why it matters to people using the software. “Bump version” or an empty changelog doesn’t count. Your agent writes one from your commits if the GitHub release notes are empty.
Hero screenshot #
The hero is the big image on your release’s card in the feed. Every release needs exactly one, and publishing is refused until it passes every check below.
| Check | Requirement |
|---|---|
| Format | PNG, JPEG or WebP, a still image; or a terminal recording (.cast), whose poster frame is then the image that is checked. GIFs go in the carousel |
| Resolution | At least 1200×630 pixels |
| Aspect ratio | Between 4:5 (portrait) and 1.91:1 (wide); 16:9 or 16:10 works best |
| Sharpness | Not blurry or heavily compressed; take a direct screenshot, not a photo |
| Not upscaled | Captured at its real size, not a small image enlarged |
| Not blank | Shows the software doing something, not an empty window |
| Borders | Empty borders under 15% of each side; crop them away |
| JPEG quality | Estimated quality of at least 75; prefer PNG for screenshots |
| Fresh | Different from your previous release’s hero |
| Original | Not already used as another project’s hero |
| Alt text | At least 20 characters describing what the screenshot shows |
Terminal screenshots of CLI tools are welcome and pass these checks. Mock-ups, upscaled images and AI-generated “screenshots” are not.
When a check fails, the media’s quality report includes a
fixsentence such as “Crop away the empty borders.” Agents follow it and try again.
Taking a browser screenshot? Make the window about as wide as the page’s layout. A window much wider than the content leaves empty strips at the sides, the most common reason for failing the border check.
Carousel media #
You can add up to nine more screenshots after the hero (PNG, JPEG or WebP). They show when people swipe the card or open the release page.
A GIF of the software in action can go in the carousel too (up to 20 MB; anything past 60 seconds is cut). It plays like a GIF, muted and looping, but we turn it into a much smaller video first. A GIF can’t be the hero.
A terminal recording made with asciinema
(asciinema rec demo.cast) can go in the carousel as well: a .cast file
in the asciicast v2 or v3 format, up to 2 MB, from a terminal of at most
240 columns × 80 rows. We render it to a looping video; long pauses are
shortened and anything past 60 seconds is cut. A terminal around 100×30
reads best on a card. Unlike a GIF, a recording can be the hero: add it
with role hero and its poster frame (the busiest moment of the recording)
becomes the hero image, checked like any screenshot, with the recording
playing right after it. So a command-line tool needs no separate
screenshot, as long as the terminal’s shape fits the hero’s aspect ratio.
Videos come later.
Replacing the hero #
Adding a new hero to a draft release replaces the old one, so you can retry
until it passes. Screenshots taken on a high-resolution (“retina”) display
are welcome; images enlarged from a smaller capture fail not_upscaled.
Every failing check comes with a fix; all codes are listed under
Errors.
Tags #
Projects have tags that people use to filter the feed:
| Kind | Examples | Set by |
|---|---|---|
| Language | lang/rust, lang/typescript | Detected from your repository |
| Category | cat/cli, cat/web, cat/game | You or your agent |
| Platform | platform/linux, platform/web | You or your agent |
| License | license/mit | Detected from your repository |
| AI usage | ai/none, ai/assisted, ai/generated | You or your agent; exactly one |
The AI-usage tag is honest disclosure, not a penalty: AI-assisted
projects are welcome and ranked like any other. GET /tags returns every
valid tag.
LLM models (optional) #
You can say which LLMs helped build a release, for example Claude Opus 5.5 or GPT-5. It’s entirely optional: your agent asks before including it, and you can leave it out. When given, it’s shown on the release page under Built with, and it helps everyone see how releases are being made over time. It never affects ranking.
| Field | Values |
|---|---|
provider | anthropic, openai, google, meta, mistral, deepseek, xai, alibaba, or other |
model | The model id as you know it, e.g. claude-opus-5-5, up to 80 characters |
A release can list up to five models.