Stdlib Readme Format

stdlib README Format

This skill defines the exact structure and rules for every lib/stdlibs/ballerina/<name>/0.0.1/go1.27/README.md. It can be invoked standalone to audit or fix an existing README, or embedded in another workflow (e.g. add-stdlib-support, fill-stdlib-gap) when writing a new one.

Template

Use this skeleton exactly. Do not add, remove, or reorder sections. One permitted extension: a large module may group its support tables under ### subsections inside Go Native Interpreter Support Status (e.g. http's ### Client / ### Request / ### Response), each subsection holding its own three-column table.

# Ballerina <Name> Library

## Overview

<Brief description of the full jBallerina module scope, ending with one sentence stating which subset the Go Native Interpreter currently supports.>

## Key Functionalities

<Bullet list of what the Go-native version currently supports — not the full jBallerina feature set.>

## Examples

```ballerina
<Short working example using only currently supported APIs.>
```

## Go Native Interpreter Support Status

This library is currently being migrated to Go to support the Ballerina Native Interpreter. The table below outlines the current support level for various features of this library in the Go implementation.

Support Levels:

- **Supported**: Fully implemented and tested in the Go version.
- **Partially Supported**: Implemented but lacking some edge cases, options, or sub-features. (See comments).
- **Not Yet Supported**: Planned for migration, but not yet implemented.
- **Cannot Support**: Cannot be implemented in the Go version due to technical limitations or architectural differences. (See comments).

| Feature/API | Support Status | Comments / Limitations |
|---|---|---|
| ... | ... | ... |

### Notable Behavioural Changes

<Use bullet points with bold headers, one bullet per divergence. Format each as:
- **<Short title>.** <jBallerina behaviour>; the Go-native version <Go-native behaviour> — <reason if helpful>.

If there are no notable behavioural changes, write:
There are **no** notable behavioural changes in the Go-native version compared to the original jBallerina implementation for the currently supported features.>

Column rules

Feature/API column

• Prose only. No backtick function names, type names, or object names anywhere in this column — not even in parentheses. Wrong: "File read — string (\fileReadString`)". Right: "File read — string"`.
• Function and type names belong in the Comments / Limitations column only.

Support Status column

Exactly one of: Supported, Partially Supported, Not Yet Supported, Cannot Support.

Comments / Limitations column

• Supported rows with no caveat — leave this cell empty. Do not write "Fully implemented and tested in the Go version." — that is implied by the status.
• Supported rows with a caveat — write only the caveat. Function names, type names, and signatures are allowed here.
• Partially Supported / Not Yet Supported / Cannot Support — explain the gap. Include relevant function or type names here.

Table separator

Always |---|---|---|. Never wide-padded column separators.

Notable Behavioural Changes rules

• Format: bullet list with a bold header followed by a period, then a sentence. Example: - **Title.** jBallerina does X; the Go-native version does Y — reason.
• Content: only permanent, architectural Go-level constraints that cannot be resolved in the native/ layer.
• Do not include:
  • Temporary language gaps that will be fixed when the interpreter gains the feature (e.g. distinct error subtypes, readonly & intersections, stream type, XML, full typedesc parameter handling). These belong in the support table as Not Yet Supported or Partially Supported.
  • Entries that say "identical" or "matching" — if the behaviour is identical, it is not a change.
  • Future potential divergences for features that are Not Yet Supported — document those in the Comments column of the relevant table row instead.
• If there are no permanent changes, write the "no changes" sentence from the template rather than omitting the section.

Validation

Mechanical checks — run the script

From the repo root:

python3 .agents/skills/stdlib-readme-format/scripts/check_readmes.py

It validates every per-package README and the aggregator in one pass: required sections and their order, status values, |---|---|---| separators, no backticks in Feature/API cells, no "Fully implemented and tested" filler in Supported rows, non-empty Comments on every gap row, bullet format, bullets-vs-"no changes"-sentence consistency, aggregator counts/percentages/Total footer recomputed from the per-package tables, verbatim bullet mirroring, and the closing "no changes" sentence membership. It must exit 0 before you save — fix every FAIL line it prints.

Judgment checks — verify by hand

The script cannot check these; confirm each is YES:

• Every Supported row's Comments cell is either empty or a meaningful caveat
• If the module declares a module-level error type (e.g. io:Error), the table has a row tracking it with an accurate status — Partially Supported with a distinct comment when the type ships as a plain alias, Not Yet Supported when it isn't declared at all
• No bullet describes behaviour identical to jBallerina
• No bullet describes a temporary language gap (distinct, readonly &, stream, etc.) — those belong in the support table
• No bullet describes a future feature's potential divergence
• Key Functionalities reflects only currently supported features
• Examples use only currently supported APIs
• No Not Yet Supported row that was just implemented in this session