# Release requirements The changelog, hero screenshot and tags every release needs, and how they're checked. 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`](/docs/api-endpoints#releases). ## 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. > [!TIP] > When a check fails, the media's quality report includes a `fix` sentence > such as "Crop away the empty borders." Agents follow it and try again. > [!TIP] > 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](https://asciinema.org) (`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](/docs/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.