Pony Library Readme

Pony Library README Conventions

These conventions are derived from existing ponylang library READMEs and should be followed when writing or updating a README.md for a Pony library project.

Load pony-prose for how the prose reads. This skill says what a README holds; pony-prose says how to write it plainly.

Required Sections (in order)

Every Pony library README has these sections in this order:

1. Title (#) — Lowercase matching the repo/package name (e.g., # glob, # web_link). Use proper capitalization only for proper nouns or acronyms (e.g., # PEG, # Lori, # GitHub REST API).

2. Intro paragraph (no heading) — 1-2 sentences describing what the library does. No section heading.

3. ## Status — Short maturity statement. Common values:

   • Production ready.
   • Beta
   • [Name] is beta-level software.
   • Longer form: [Name] is beta quality software that will change frequently. Expect breaking changes. That said, you should feel comfortable using it in your projects.

4. ## Installation — Standard 5-bullet list using * markers:

   * Install [corral](https://github.com/ponylang/corral)
   * `corral add github.com/ponylang/<name>.git --version <X.Y.Z>`
   * `corral fetch` to fetch your dependencies
   * `use "<package>"` to include this package
   * `corral run -- ponyc` to compile your application
   

   If the package has sub-packages, the use bullet gets sub-bullets listing each (e.g., use "ssl/crypto", use "ssl/net").

5. ## API Documentation — A markdown link to the docs: [https://ponylang.github.io/<name>](https://ponylang.github.io/<name>). This is always the last section (or near-last if a project-specific section follows).

Optional Sections

These go between Installation and API Documentation, in this order:

• ## Dependencies — Only include when the library requires native C libraries the user must install (e.g., libpcre2, OpenSSL). If the dependency is transitive via the ssl package, a note after the installation bullets linking to ssl's installation instructions is sufficient instead of a full section.

• ## Usage — Always include an inline code example showing core usage (a complete short program or a structural skeleton). Point to the examples/ directory for more.

Things Pony Library READMEs Do NOT Have

• No CI/coverage/version badges
• No "Contributing" section (that goes in CONTRIBUTING.md)
• No "License" section (that goes in LICENSE)
• No "Table of Contents"