[P2][DOCS] Make the guide say which release it documents; tag and catch crates.io up with main

Open
  • Is something wrong?
#246 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
45/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Active
Tech stack
github-actions, rust
Domain
documentation, release

Research direction

Start with book/src/getting-started.md and the guide pages cited in the issue, then read .github/workflows/pages.yml and release.yml to understand the current publishing flow. Check the published crate version and existing tags before choosing how to handle the release-history gap. Done means the guide identifies its version, its dependency instructions compile the cited examples, and each crates.io release has a matching tag.

Written by the indexing model from the issue text.

Description

area: build documentation help wanted priority: P2 type: feature

Evidence and problem

The guide is deployed from every push to main (.github/workflows/pages.yml, on: push: branches: [main]), but a new user installs the engine from crates.io, as book/src/getting-started.md says:

cargo new my_game && cd my_game
cargo add ponko

That gives ponko 0.0.1 / ponko_ecs 0.0.1, published 2026-11-08 (cargo search ponko). Everything merged since then is in the published guide but not in that crate. I downloaded the published .crate files and searched them:

Guide shows Chapter In ponko 0.0.1 / ponko_ecs 0.0.1?
actions! { struct Act { … } }, ActionId, Act::resolve(ctx) actions.md (via examples/action_map.rs:action_map) no (macro_rules! actions, struct ActionId absent)
InputScenario, Game::input_scenario actions.md:30 no
ctx.world.resource_scope::<Total, _>(…) ecs.md:192-199 no (fn resource_scope absent from ponko_ecs-0.0.1/src/world.rs)
UiTheme, ui.set_theme, UiLayout presets, widget builders ui.md:40-66 no
capabilities / instance_capabilities control.md:114, agents.md:40 no
Phase, Game::add, MemorySource, add_asset_source rustdoc API reference (/api, same deploy) no

So a reader who copies the "Named input actions" example into a fresh cargo add ponko project gets cannot find macro actions. There is also nothing in the guide saying which version it describes. The repo has no v0.0.1 tag (git tag lists only v1.0.0, from before the rename), so a reader can't even pick the matching source.

Goal and staged scope

  1. Say what version the guide describes. Add a banner or introduction note: "This guide follows main. For the released crate, use ponko = { git = "https://github.com/ponkoengine/ponko" } or the guide for vX". Have getting-started.md show the git dependency next to cargo add ponko until a release catches up.
  2. Tag releases. Tag the commit that 0.0.1 was published from (or document that it was published untagged), and make sure future crates.io publishes go through release.yml so the tag, CHANGELOG section and crate match.
  3. Optional, pick one: (a) deploy a versioned copy of the guide per release tag (/ponko/v0.0.2/) next to the main one, or (b) mark guide sections for unreleased APIs with an "Unreleased" note that the release script removes.
  4. Cut 0.0.2 (or the next version) once the current [Unreleased] CHANGELOG section is ready, so crates.io catches up with the guide.

Non-goals

No change to the semver promise in STABILITY.md. No docs.rs work (docs.rs already builds per version).

Acceptance

  • The guide's introduction or each page says which version it documents, and getting-started.md gives a dependency line that compiles the guide's examples.
  • Every crates.io version has a matching git tag.
  • A reader following actions.md with the dependency line from getting-started.md compiles without errors.
Dominant language
Rust
Stars
4
Forks
0
Avg merge
45m
Merged PRs (30d)
199

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from ponkoengine/ponko

All issues in ponkoengine/ponko

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.