Sdk Readme

• users: Install / Quick start / API / Configuration
• contributors: Development / Testing / Releasing / Contributing

Monorepo Root README

Required structure

# {Repo Title}

{One-sentence description: language + purpose + quality signal}

## Packages

{Table: package link, description, registry badge}

## Examples

{Table: example path, description, port, framework} # only if examples exist

## Quick Start

{Short navigation text pointing to per-package READMEs. No code block.}

## Development

### Prerequisites

{Bullet list of required tools with links}

### Setup

{Single bash block: install, build, test}

### Development Workflow

{Table: Step | Command | Description}

### Monorepo Scripts

{Table: Script | Description (all root scripts)}

## Testing

{Short intro + bash block with 3 commands: all, watch, one package}

## Releasing

{Numbered release flow ending with GitHub Actions workflow link}

## Documentation

{Links to package READMEs / API docs}

## Contributing

{Standard 5-step fork flow}

## License

{Link to LICENSE file}

## Links

{Website + Documentation + GitHub repository}

Conventions

• Title: plain product naming (e.g., Altertable JavaScript SDK).
• Opening sentence: concise, specific, and quality-oriented (e.g., “modern”, “type-safe”, “production-grade”).
• Packages table columns: Package, Description, registry column (NPM, PyPI, etc.).
• Registry badges: use shields.io linked to the package page.
• Quick Start: act as routing layer to package docs, not duplicate package install/API.
• Monorepo Scripts: document every root manifest script (no hidden scripts).
• Testing: always show full suite + watch mode + package-scoped execution.
• Links: always include:
  • Website: https://altertable.ai
  • Documentation: https://altertable.ai/docs
  • GitHub repository URL

Canonical reference: altertable-js root README.

Package README

Required section order

1. One-line description
2. ## Install
3. ## Quick start
4. ## API reference
5. ## Configuration
6. ## Development
7. ## License

Content rules

1) One-line description

• State what the package does and where it runs.
• Keep it concrete; avoid marketing fluff.

2) Install

• Show one canonical install command only.
• Use ecosystem-native manager (npm install, pip install, gem install, etc.).

3) Quick start

• Must be runnable copy/paste code (imports + init + one key action).
• Keep under ~20 lines.
• Analytics SDKs: include one track call.
• Lakehouse SDKs: include one query execution.

4) API reference

• Document every public method.
• For each method include:
  • signature (or exact command form for CLI)
  • one-line behavior description
  • minimal usage snippet when useful
• Group by capability (Initialization, Tracking, Identity, Querying, etc.).

5) Configuration

Use a single table:

Include all configurable keys/env vars, including defaults and requiredness.

6) Development

• Include prerequisites (tool + minimum version).
• Include exact dependency install command.
• Include exact test command.
• Include exact lint command.
• Prefer one compact code block.

7) License

• Link to repository LICENSE file.
• Do not paste full license text in README.

Framework package add-on

If package targets a framework (e.g., React), add ## Usage between Quick start and API reference to show provider/setup and common integration pattern.

Style and formatting

• Write in second person and present tense.
• Keep prose short; favor tables, bullets, and runnable snippets.
• Use inline code for methods, commands, env vars, paths, config keys.
• Keep heading capitalization consistent (Quick start, API reference).
• Avoid duplicate content across root and package READMEs.
• Avoid broken promises (“coming soon”, TODO sections) in committed README files.

Review checklist (before commit)

• Required sections exist and are in required order.
• All code blocks are syntactically valid and plausible to run.
• API reference covers all public methods/commands.
• Configuration table is complete and accurate.
• Development commands match real project tooling.
• License points to LICENSE.
• Root README (monorepo) links package docs instead of duplicating them.
• Badges and links resolve correctly.