Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
287 lines (204 loc) · 10.5 KB

CONTRIBUTING.md

File metadata and controls

287 lines (204 loc) · 10.5 KB
Raw

Contributing to Ranu.js

PRs Welcome Code of Conduct Security Policy Conventional Commits

Thank you for your interest in contributing to Ranu.js!

Ranu.js is an open-source project, and contributions from the community are warmly welcomed. Whether you are fixing typos, improving documentation, submitting bug fixes, or proposing new framework features, this guide will help you get started smoothly.

Note

Public Alpha Stage
Ranu.js is currently in Public Alpha development. Architecture, APIs, package boundaries, and internal workflows are actively evolving as the project progresses toward the stable V1 milestone.

Important

External Contribution Policy (Prior Approval Required)
To protect framework stability, API consistency, and security during our Public Alpha development, direct Pull Requests from external contributors are not accepted without prior permission.
Before writing code or opening a PR, please submit a Contribution & Permission Request issue. Once maintainers approve your proposal (or apply the contribution: approved label), you are warmly welcomed to submit your PR. Direct unapproved PRs will be held by our automated gatekeeper bot until permission is granted.

Quick Contribution Decision Matrix

To save your time and keep contributions streamlined, refer to this quick guide:

Type of Contribution Permission Request First? Changeset Required? Example Commit Prefix
New Feature / API Change ✅ Yes (Open Issue first) ✅ Yes feat(runtime): add response streaming support
Bug Fix (Kernel / Adapters / AI) ✅ Yes (Open Issue first) ✅ Yes (if in published package) fix(router): resolve dynamic segment matching
Documentation / Typo Fixes ✅ Yes (Open Issue first) ❌ No docs: fix routing example typo
Tests & Internal Tooling ✅ Yes (Open Issue first) ❌ No test: add unit tests for cookie parsing
Refactoring (Architecture) ✅ Yes (Open Issue first) ❌ No refactor(build): simplify module graph traversal

Development Setup

Ranu.js is developed as a pnpm monorepo.

Prerequisites

  • Node.js >= 22.0.0
  • pnpm >= 11.0.0

To enable or install pnpm:

# Option 1: Using Corepack (recommended)
corepack enable

# Option 2: Using npm globally
npm install -g pnpm

Clone and Bootstrap

# 1. Clone the repository
git clone https://github.com/hoslift/ranu.js.git
cd ranu.js

# 2. Install dependencies across all packages
pnpm install

# 3. Build all workspace packages
pnpm build

Repository Structure

The monorepo is organized cleanly into modular packages and directories:

Directory Purpose
packages/ Core framework packages (router, react, runtime, build, server, etc.)
adapters/ Deployment adapters (e.g., @ranujs/adapter-vercel)
create-ranu/ The official CLI scaffolder (create-ranujs)
examples/ Standalone, canonical reference applications using public APIs
fixtures/ Internal test applications used by test harnesses
tests/ End-to-end, API contract, security, and performance test suites
docs/ Specifications and public documentation
rfcs/ Architectural proposals and Request for Comments
tooling/ Internal repository configs and build tools

Development Workflow

1. Create a Branch

Always create a dedicated feature or fix branch from main:

git checkout -b <type>/<short-description>

Branch naming conventions:

  • feat/<feature-name> (e.g., feat/edge-adapter)
  • fix/<bug-name> (e.g., fix/cookie-parsing)
  • docs/<topic> (e.g., docs/quickstart-guide)
  • test/<component> (e.g., test/ssr-streaming)
  • chore/<task> (e.g., chore/bump-deps)

2. Commit Message Guidelines

Ranu.js follows the Conventional Commits standard. Please use structured commit messages:

<type>(<scope>): <short description>

Allowed Types:

  • feat: A new feature or capability
  • fix: A bug fix
  • docs: Documentation changes only
  • test: Adding or correcting tests
  • refactor: Code change that neither fixes a bug nor adds a feature
  • perf: Performance improvement
  • chore: Maintenance tasks, dependency updates, tooling

Examples:

  • feat(react): support custom error boundaries in nested layouts
  • fix(router): sanitize regex in dynamic path generation
  • docs: update npm-first quick start instructions
  • test(security): add test suite for server-only boundaries

3. Adding or Updating Tests

Any code change that alters framework runtime behavior or fixes a bug must include tests.

# Run all tests
pnpm test

# Run unit tests only
pnpm test:unit

# Run API contract tests
pnpm test:api

# Run integration tests
pnpm test:integration

4. Validating Your Changes (Pre-PR Check)

Before opening a pull request, run the local validation pipeline to ensure all checks pass:

# Complete local validation (same as CI pipeline)
pnpm prepr

Alternatively, you can run individual checks:

pnpm typecheck       # TypeScript type checking
pnpm lint            # ESLint code analysis
pnpm format:check    # Prettier formatting check
pnpm ci:verify       # Verification suite without cleaning

5. Adding a Changeset

If your pull request introduces changes to packages that are published to npm (e.g., @ranujs/core, create-ranujs, or adapters), you must include a Changeset:

pnpm changeset

Follow the interactive prompts:

  1. Select the packages affected by your change (use arrow keys and space).
  2. Choose the version impact:
    • patch: Bug fixes and minor internal updates.
    • minor: New backward-compatible features.
    • major: Breaking changes (discuss with maintainers first).
  3. Write a clear, concise summary of the change. This summary will be automatically added to CHANGELOG.md upon release.

Changes affecting only docs/, tests/, examples/, or internal tooling do not require a Changeset.

Package Versioning & Adapter Lifecycle Architecture

Ranu.js employs a structured hybrid release architecture:

  • Core Framework (@ranujs/core & create-ranujs): Kept in synchronized lockstep. When core framework releases an update, the CLI scaffolder updates alongside it so newly created projects always target the latest core engine.
  • Adapters Ecosystem (adapters/*): Independently versioned deployment plugins.
    • Public Alpha (v0.1.x): Existing and newly authored adapters start at v0.1.0 (or the active alpha line) to facilitate early iteration.
    • v1.0.0 Milestone: Upon official General Availability, the entire ecosystem (Core, CLI, and all active adapters) aligns to v1.0.0. Alpha (v0.1.x) is officially retired.
    • Post-v1.0.0 Era: Any newly authored adapter begins directly at v1.0.0 with peerDependencies: { "@ranujs/core": ">=1.0.0" }. Adapters may receive independent patch or minor updates without triggering an artificial core release.

6. Opening a Pull Request (PR)

  1. Push your branch to your fork or repository: 
    git push origin <branch-name>
  2. Open a Pull Request targeting the main branch.
  3. Complete the PR template with:
    • A clear explanation of what changed and why.
    • Links to relevant approved issue (e.g., Closes #123).
    • How the change was tested.

Contributor Checklist

Before submitting your pull request, verify:

  • A Contribution Request issue was approved prior to submitting this PR.
  • Changes are focused and do not include unrelated code or formatting changes.
  • Code follows project conventions and passes pnpm lint.
  • TypeScript compiles cleanly with pnpm typecheck.
  • Relevant unit or integration tests are added/updated and pass (pnpm test).
  • Changeset is added via pnpm changeset (if published packages were modified).
  • Local pre-PR validation passes (pnpm prepr).

Frequently Asked Questions (FAQ)

Q: Why do I need prior approval before opening a PR?

During Public Alpha development, architecture and internal APIs evolve rapidly. Requiring an approved Contribution Request ensures maintainer alignment, prevents duplicated work, and keeps the code base secure and consistent.

Q: Where can I find beginner-friendly tasks?

Check our GitHub Issues and filter by labels:

  • good first issue — Perfect for new contributors.
  • help wanted — Community contributions welcome.
  • documentation — Improvements to guides, docstrings, and examples.

Q: What should I do if CI fails on my PR?

Don't worry! Click Details on the failing GitHub Actions job to view the error log. You can reproduce the exact check locally by running:

pnpm prepr

Fix the reported error, commit, and push to your PR branch.

Q: Do I need to create a Changeset for documentation or test updates?

No. Changesets are only required when modifying code inside published packages (packages/ or adapters/).

Code of Conduct

All contributors are expected to uphold our standards of a welcoming, inclusive, and harassment-free community. Please review CODE_OF_CONDUCT.md before participating.

Security

Please do not report security vulnerabilities through public GitHub Issues. Review our SECURITY.md policy for responsible private disclosure.

License

By contributing to Ranu.js, you agree that your contributions will be licensed under the MIT License.

Ranu.js — Rethinking the Full-Stack Web.
Maintained by Hoslift.