Open Source Standards

Overview

This standard covers open source project management — from starter kits and utility libraries to community-maintained tools. Open source requires different practices from closed projects: clear onboarding, contribution guidelines, semantic versioning, and sustainable maintenance.

Prerequisites: General Standards (file structures, Git, documentation).

What this covers:

• Open source starter kits and templates
• npm packages and libraries
• GitHub repository configuration
• Community and contribution management
• Documentation and onboarding

Tech Stack (2026)

Project Scaffolding

Repository Structure (npm Package)

project-root/
├── src/                     # Source code
│   └── index.ts             # Public API exports
├── tests/                   # Vitest tests
├── docs/                    # Documentation site source
├── .github/
│   ├── workflows/           # CI/CD
│   │   ├── ci.yml           # Test + lint on PR
│   │   └── release.yml      # npm publish on tag
│   ├── ISSUE_TEMPLATE/      # Issue templates
│   └── pull_request_template.md
├── scripts/                 # Build, release helpers
├── LICENSE                  # Required for open source
├── CONTRIBUTING.md          # Contribution guide
├── CODE_OF_CONDUCT.md       # Community standards
├── CHANGELOG.md             # Auto-generated via semantic-release
├── README.md                # Project overview
├── package.json
├── tsconfig.json
└── vite.config.ts           # Vitest config

Package.json Standards

{
  "name": "@jordan-thirkle/package-name",
  "version": "0.1.0",
  "type": "module",
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  },
  "files": ["dist"],
  "sideEffects": false,
  "engines": { "node": ">=22.12.0" },
  "scripts": {
    "build": "tsup src/index.ts --format esm,cjs --dts",
    "test": "vitest run",
    "lint": "biome check src/",
    "format": "biome format --write src/",
    "prepublishOnly": "npm run build && npm test"
  }
}

README Structure

Every open source project’s README follows this structure:

# Project Name

[Short description — one or two sentences]

## Features
- Bullet list of key features

## Installation
```bash
npm install project-name

Quick Start

import { thing } from 'project-name';

API Reference

Document exported functions/types with usage examples.

Examples

Link to example projects or runnable demos.

Contributing

Link to CONTRIBUTING.md — welcome contributions.

License

MIT (or chosen license) — plain language summary.

Related

Links to related projects, blog posts, or ecosystem.

---

## Maintenance & Release

### Semantic Versioning

| Change | Version Bump | Example |
|--------|-------------|---------|
| Breaking changes | Major (1.x → 2.x) | Public API changes, removed exports |
| New features (backward compatible) | Minor (1.1 → 1.2) | New exports, optional params |
| Bug fixes (backward compatible) | Patch (1.1.1 → 1.1.2) | Internal fixes, docs |

### Automated Release Pipeline

Use `semantic-release` for fully automated releases:
1. PR merged to `main` with conventional commit
2. CI runs tests
3. `semantic-release` determines version bump from commit messages
4. CHANGELOG.md auto-updated
5. npm package published
6. GitHub release created with release notes

### Issue & PR Response Standards

| Type | Target Response | SLA |
|------|-----------------|-----|
| Bug report | First response | ≤ 48 hours |
| Feature request | Acknowledge + roadmap | ≤ 1 week |
| Pull request | Initial review | ≤ 72 hours |
| Security report | Immediate (private) | ≤ 24 hours |

---

## Community Standards

### Required Files

Every open source repo must include:
- **LICENSE** — MIT is the default choice (permissive, widely adopted)
- **CONTRIBUTING.md** — How to set up, develop, test, and submit changes
- **CODE_OF_CONDUCT.md** — Contributor Covenant v2.1 (industry standard)
- **README.md** — Project overview and quick start
- **.github/ISSUE_TEMPLATE/** — Bug report + feature request templates

### CONTRIBUTING.md Template

```markdown
# Contributing to [Project]

Thanks for considering contributing!

## Development Setup
1. Clone the repo
2. `npm install`
3. `npm test` — verify tests pass before making changes

## Making Changes
1. Create a branch: `git checkout -b feat/my-feature`
2. Make changes with tests
3. Run `npm run lint` and `npm test`
4. Commit with conventional commit format
5. Push and open a PR

## Pull Request Guidelines
- Keep PRs focused on a single change
- Include tests for new functionality
- Update documentation if public API changes
- Ensure CI passes before requesting review

## Code Style
- TypeScript strict mode
- Biome for formatting
- No unused imports or variables

License Selection Guide

Default recommendation: MIT. It’s understood, permissive, and never causes compatibility issues.

Review & Shipping Checklist

• LICENSE file present (MIT default)
• README with installation, quick start, and API reference
• CONTRIBUTING.md with setup and PR guidelines
• CODE_OF_CONDUCT.md (Contributor Covenant)
• Issue templates configured (bug report + feature request)
• PR template configured
• CI/CD pipeline (test + lint on every PR)
• Automated release pipeline (semantic-release)
• CHANGELOG.md auto-generated
• Package published to npm (or relevant registry)
• GitHub topics set for discoverability
• .npmignore or files field in package.json (don’t publish source files)
• Security policy (SECURITY.md) for vulnerability reporting

Trends to Watch (2026+)

• AI-assisted open source — LLMs helping contributors write code, docs, and tests
• Package registry consolidation — npm remains dominant, but JSR and other registries emerging
• Supply chain security — npm audit, SBOMs, and dependency review becoming standard CI steps
• Monorepo tooling — Turborepo, Nx, and pnpm workspaces for multi-package projects
• Documentation as code — Vitepress, Astro docs, and MDX for source-driven documentation

Project Templates

• Astro Starter Kit — Reference: open source starter kit with full README, contribution guide, and CI/CD

References

• Astro Starter Kit project page — Production open source project structure
• External: Open Source Guide, Choose a License, semantic-release, Contributor Covenant