Contributing to ObjectStack Protocol

Thank you for your interest in contributing to ObjectStack! This guide will help you get started with contributing to the protocol specifications.

📋 Table of Contents

Code of Conduct
Getting Started
Development Workflow
Contribution Types
Coding Standards
Testing Guidelines
Documentation Guidelines
Pull Request Process
Community

Code of Conduct

We are committed to providing a welcoming and inclusive environment. Please be respectful and professional in all interactions.

Getting Started

Prerequisites

Node.js >= 18.0.0
PNPM >= 8.0.0
Git >= 2.0.0

Initial Setup

# 1. Fork the repository on GitHub
# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/spec.git
cd spec

# 3. Add upstream remote
git remote add upstream https://github.com/objectstack-ai/spec.git

# 4. Install dependencies
pnpm install

# 5. Build the project
pnpm build

# 6. Run tests
pnpm test

Development Workflow

1. Choose What to Work On

Before starting, review:

PRIORITIES.md - Current sprint priorities
DEVELOPMENT_ROADMAP.md - Long-term roadmap
GitHub Issues - Open issues

2. Create a Branch

# Update your main branch
git checkout main
git pull upstream main

# Create a feature branch
git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

3. Make Your Changes

Follow the Coding Standards and ensure:

Changes are minimal and focused
Code follows existing patterns
Tests are added/updated
Documentation is updated

4. Test Your Changes

# Run all tests
pnpm test

# Run tests for specific package
pnpm --filter @objectstack/spec test

# Build to verify schemas
pnpm build

5. Submit Your Changes

# Stage your changes
git add .

# Commit with descriptive message
git commit -m "feat: add new field type for encrypted data"

# Push to your fork
git push origin feature/your-feature-name

# Create Pull Request on GitHub

Contribution Types

🔧 Protocol Definitions

Adding or modifying protocol definitions in packages/spec/src/:

Create Zod Schema - Always start here
Add JSDoc Comments - Document with @description
Write Tests - Target 80%+ coverage
Generate Schemas - Run pnpm build
Create Documentation - Add MDX in content/docs/references/

Example:

/**
 * Represents an encrypted field for storing sensitive data
 * @description Provides end-to-end encryption for sensitive information
 */
export const EncryptedFieldSchema = z.object({
  /** Field type identifier */
  type: z.literal('encrypted'),
  
  /** Encryption algorithm (default: AES-256-GCM) */
  algorithm: z.enum(['aes-256-gcm', 'rsa-4096']).default('aes-256-gcm'),
  
  /** Key management strategy */
  keyManagement: z.enum(['user', 'organization', 'system']).default('organization'),
});

📚 Documentation

Concepts - High-level explanations in content/docs/concepts/
Guides - How-to tutorials in content/docs/guides/
References - API documentation in content/docs/references/
Specifications - Protocol specs in content/docs/specifications/

🐛 Bug Fixes

Create an issue describing the bug (if not exists)
Reference the issue in your PR
Add regression tests
Update documentation if behavior changes

✨ Examples

Add working examples in examples/:

Include README.md with setup instructions
Provide objectstack.config.ts configuration
Add CHANGELOG.md for version history

Coding Standards

Naming Conventions

CRITICAL: Follow these naming conventions strictly:

Configuration Keys (TypeScript Properties)

Use camelCase:

{
  maxLength: 100,
  referenceFilters: ['active'],
  defaultValue: 'none',
}

Machine Names (Data Values)

Use snake_case:

{
  name: 'project_task',
  object: 'account',
  field: 'first_name',
}

Schema Definition Pattern

import { z } from 'zod';

/**
 * Schema description
 * @description Detailed explanation
 */
export const MySchema = z.object({
  /** Property description */
  propertyName: z.string().describe('Property description'),
  
  /** Another property */
  anotherProperty: z.number().optional().describe('Optional property'),
});

export type MyType = z.infer<typeof MySchema>;

File Organization

packages/spec/src/
├── data/           # ObjectQL - Data Protocol
│   ├── field.zod.ts
│   ├── object.zod.ts
│   └── validation.zod.ts
├── ui/             # ObjectUI - UI Protocol
│   ├── app.zod.ts
│   ├── view.zod.ts
│   └── theme.zod.ts
├── system/         # ObjectOS - System Protocol
│   ├── manifest.zod.ts
│   ├── plugin.zod.ts
│   └── driver.zod.ts
├── ai/             # AI Protocol
│   ├── agent.zod.ts
│   └── model.zod.ts
└── api/            # API Protocol
    ├── envelopes.zod.ts
    └── requests.zod.ts

Testing Guidelines

Test Coverage

Target: 80%+ code coverage
Location: Co-located *.test.ts files
Framework: Vitest

Test Structure

import { describe, it, expect } from 'vitest';
import { MySchema } from './my-schema.zod';

describe('MySchema', () => {
  describe('validation', () => {
    it('should accept valid data', () => {
      const result = MySchema.safeParse({
        propertyName: 'valid value',
      });
      expect(result.success).toBe(true);
    });

    it('should reject invalid data', () => {
      const result = MySchema.safeParse({
        propertyName: 123, // wrong type
      });
      expect(result.success).toBe(false);
    });
  });

  describe('type inference', () => {
    it('should infer correct TypeScript types', () => {
      type MyType = z.infer<typeof MySchema>;
      const data: MyType = {
        propertyName: 'value',
      };
      expect(data.propertyName).toBe('value');
    });
  });
});

Documentation Guidelines

MDX Documentation

Create documentation in content/docs/references/ matching the source structure:

---
title: MySchema
description: Schema description for SEO and navigation
---

# MySchema

Brief description of what this schema represents.

## Overview

Detailed explanation of the schema's purpose and use cases.

## Schema Definition

\`\`\`typescript
import { MySchema } from '@objectstack/spec';

const config = {
  propertyName: 'value',
};

const validated = MySchema.parse(config);
\`\`\`

## Properties

### propertyName

- **Type**: `string`
- **Required**: Yes
- **Description**: Description of this property

## Examples

### Basic Usage

\`\`\`typescript
const basic = {
  propertyName: 'simple value',
};
\`\`\`

### Advanced Usage

\`\`\`typescript
const advanced = {
  propertyName: 'complex value',
  anotherProperty: 42,
};
\`\`\`

## Related

- [RelatedSchema](./related-schema)
- [AnotherSchema](./another-schema)

Bilingual Support

Provide both English and Chinese versions:

English: my-schema.mdx
Chinese: my-schema.cn.mdx

Pull Request Process

Before Submitting

All tests pass (pnpm test)
Code builds successfully (pnpm build)
Documentation is updated
Naming conventions are followed
JSDoc comments are complete
No unrelated changes included

PR Checklist

Use this template for your PR description:

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Changes Made
- Item 1
- Item 2

## Testing
- [ ] Unit tests added/updated
- [ ] All tests passing
- [ ] Manual testing completed

## Documentation
- [ ] JSDoc comments added
- [ ] MDX documentation created/updated
- [ ] Examples provided

## Checklist
- [ ] Zod schema follows naming conventions
- [ ] Comprehensive JSDoc comments with @description
- [ ] Unit tests with 80%+ coverage
- [ ] Documentation with examples
- [ ] JSON schema generated successfully
- [ ] All existing tests pass

Review Process

Automated Checks - CI/CD runs tests and builds
Code Review - Maintainers review your code
Feedback - Address review comments
Approval - At least one maintainer approval required
Merge - Maintainers will merge when ready

Community

Communication Channels

GitHub Discussions - General questions and discussions
GitHub Issues - Bug reports and feature requests
Pull Requests - Code contributions

Getting Help

Review PLANNING_INDEX.md for documentation navigation
Check ARCHITECTURE.md for system design
Read QUICK_START_IMPLEMENTATION.md for implementation examples

Recognition

Contributors will be:

Listed in release notes
Mentioned in the CHANGELOG
Credited in documentation (where applicable)

License

By contributing, you agree that your contributions will be licensed under the Apache 2.0 License.

Questions? Open a GitHub Discussion

Need Help? Check the documentation or ask in discussions

Thank you for contributing to ObjectStack! 🚀

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History