Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
288 lines (190 loc) · 11.3 KB

CONTRIBUTING.md

File metadata and controls

288 lines (190 loc) · 11.3 KB

Contributing

Prerequisites

Before contributing, please ensure you have the following installed:

  • Node.js (version 22)
  • npm (version 10 - included with Node.js)

Set Up

  1. Install the dependencies:
npm install
  1. Start the development server:
npm run dev
  1. Make and test your changes
  2. Format your code:
npm run format:write
  1. Push changes to a branch and create a pull request

Site Organization

This site is powered by Docusaurus. The documentation is split into four distinct sections, each serving a different purpose and configured as its own Docusaurus plugin instance.

The Four Sections

Section URL Purpose
Learn /learn Guides, tutorials, and conceptual introductions. How-to content that walks users through a goal.
Reference /reference/vN Complete technical reference for every feature, API, configuration option, and operation. Versioned by major Harper version.
Release Notes /release-notes Changelog for every Harper release. Organized by major version codename (e.g. v4-tucker).
Fabric /fabric Documentation for Harper's managed cloud platform. Separate from the core Harper product docs.

Rule of thumb: if it explains how something works or what something does, it belongs in Reference. If it explains how to accomplish something, it belongs in Learn. New feature documentation always goes in Reference first; Learn guides can link to it.

Section Configuration Map

Each section maps to specific source directories and config files:

Learn

Item Location
Content learn/
Sidebar sidebarsLearn.ts
Plugin config docusaurus.config.ts → plugin id learn

Learn is non-versioned. All content lives directly in learn/ organized into categories that match the sidebar.

Reference

Item Location
Current (v5) content reference/
Archived (v4) content reference_versioned_docs/version-v4/
Current sidebar sidebarsReference.ts
v4 sidebar reference_versioned_sidebars/version-v4-sidebars.json
Version list reference_versions.json
Plugin config docusaurus.config.ts → plugin id reference

Reference is versioned by major Harper version. The reference_versions.json file lists all archived versions — currently ["current", "v4"]. The current version maps to v5 (the in-progress next major) and is not published; v4 is the default displayed version.

To cut a new version snapshot (e.g. when v5 ships), run:

node scripts/cut-version.js

Release Notes

Item Location
Content release-notes/
Sidebar sidebarsReleaseNotes.ts
Plugin config docusaurus.config.ts → plugin id release-notes

Release notes are non-versioned in the Docusaurus sense — major version organization is handled manually via subdirectories (v4-tucker/, v3-monkey/, etc.). The sidebar uses autogenerated directives so new files are picked up automatically. See the Release Notes Process section for the full workflow.

Fabric

Item Location
Content fabric/
Sidebar sidebarsFabric.ts
Plugin config docusaurus.config.ts → plugin id fabric

Fabric is non-versioned. It documents the managed cloud platform independently of the Harper core product.

Reference Section Structure

The Reference section is organized as a flat list of feature-based sections — no deep nesting. Each top-level section corresponds to one Harper feature or subsystem.

Section Layout

Every section follows this pattern:

reference/
└── {feature}/
    ├── overview.md        # General introduction, architecture, concepts
    ├── configuration.md   # Config options specific to this feature (if applicable)
    ├── api.md             # JS/programmatic API reference (if applicable)
    └── operations.md      # Operations API operations for this feature (if applicable)

Not every section needs all four files — some features only warrant an overview.md. The filenames above are conventions, not requirements.

Section Order

Sections are ordered in the sidebar by who needs them first:

  1. Data & Application — Database, Resources, Components
  2. Access & Security — REST, HTTP, Security, Users & Roles
  3. Setup & Operation — CLI, Configuration, Operations API
  4. Features — Logging, Analytics, MQTT, Static Files, Environment Variables, Replication, GraphQL Querying, Studio, Fastify Routes
  5. Legacy — Deprecated or discouraged features

Sidebar Headers

Reference sidebar headers use className: "reference-category-header" for compact styling. This is set on each category entry in the sidebar config. Do not use learn-category-header in reference sidebars.

Legacy Section

Deprecated or discouraged features belong in reference/legacy/ (current) or reference_versioned_docs/version-v4/legacy/ (v4). Each legacy page should briefly explain what the feature was and direct users to the modern alternative.

Version Annotations

Because the Reference section consolidates all minor versions of a major into one document, features are annotated inline to indicate when they were introduced or changed.

Use the <VersionBadge> component. It is registered globally and requires no import in .md or .mdx files.

<VersionBadge version="v4.3.0" />
<VersionBadge type="changed" version="v4.5.0" />
<VersionBadge type="deprecated" version="v4.2.0" />

The type prop defaults to "added", so the most common case is just version. Place the badge on its own line directly below the heading it describes:

New feature:

## Relationships

<VersionBadge version="v4.3.0" />

The `@relation` directive allows you to define relationships between tables...

Changed behavior:

### Default Port

<VersionBadge type="changed" version="v4.5.0" />

The default MQTT port changed from 9925 to 9933.
In previous versions of v4, the default was 9925.

Deprecated feature:

## SQL Querying

<VersionBadge type="deprecated" version="v4.2.0" />

SQL is still supported but discouraged. See [Database](../database/overview.md) for modern alternatives.

Configuration option (inline in a list):

- `logger.level` — Log level; _Default_: `"info"` (Added in: v4.1.0)

For inline config option annotations inside list items, plain text (Added in: vX.Y.Z) is fine — using the component mid-sentence is awkward. Reserve <VersionBadge> for standalone placement after headings.

If the introduction version is inferred rather than confirmed by release notes, append a note:

<VersionBadge version="v4.3.0" /> (inferred from version comparison, needs verification)

Known Issues

docusaurus serve 404s on /docs/4.X paths

docusaurus serve uses serve-handler, which treats ending URL path segments containing a singular dot (e.g. 4.6) as file extensions rather than directory names. This causes /docs/4.6 to 404 locally even though the redirect page exists at build/docs/4.6/index.html. This doesn't apply to nested paths such as /docs/4.6/developers.

A fix has been submitted upstream at vercel/serve-handler#230. Once it merges and Docusaurus upgrades its dependency, the local patch can be removed.

In the meantime, if you need to test these redirects locally, apply a change in node_modules/serve-handler/src/index.js around line 608 where you clear the stats variable from lstat if it is a directory so it falls through to the nested index.html.

if (path.extname(relativePath) !== '') {
	try {
		stats = await handlers.lstat(absolutePath);
		if (stats && stats.isDirectory()) {
			stats = null;
		}
	} catch (err) {
		if (err.code !== 'ENOENT' && err.code !== 'ENOTDIR') {
			return internalError(absolutePath, response, acceptsJSON, current, handlers, config, err);
		}
	}
}

Release Notes Process

When adding release notes for a new HarperDB version, follow these steps:

1. Create the Release Note File

Add a new markdown file in the appropriate version directory:

  • Path: release-notes/v4-tucker/{version}.md (e.g., 4.7.1.md)
  • Include the standard frontmatter with title
  • Add the date and version details
  • List all changes, fixes, and improvements

Example structure:

---
title: 4.7.1
---

# 4.7.1

MM/DD/YYYY

- Feature or fix description
- Another change description

For alpha/beta releases, include the appropriate warning admonition.

2. Update the Version Index (Minor Versions Only)

For new minor versions (e.g., 4.8.0), update the version index file at release-notes/v4-tucker/index.mdx:

  • Add a new <LatestPatchLink> component section for the new minor version
  • Include a summary of the major features introduced in that minor version line
  • Place the newest minor version at the top of the file

Note: For patch releases (e.g., 4.7.1, 4.7.2), you do NOT need to update the index file. The <LatestPatchLink> component automatically finds and links to the latest patch version.

Example:

## <LatestPatchLink major={4} minor={7} label="4.7" />

- Major feature summary for 4.7.x releases
- Another significant capability added

3. Automatic Updates

The following updates happen automatically through the system:

  • Sidebar Navigation: The release notes sidebar uses autogenerated directives, so new release note files are automatically included
  • Latest Version Links: The <LatestPatchLink> component automatically finds and links to the latest patch version for a given major.minor combination
  • Sorting: Release notes are automatically sorted by semantic version in the sidebar

4. Considerations

  • Release notes are separate from the main documentation versioning system
  • All release notes live in the release-notes/ directory, not in versioned_docs/
  • The release notes plugin is configured in docusaurus.config.ts with its own routing and sidebar
  • The main navigation links directly to v4 Tucker release notes as the default