8.contributing.md

Contributing Guide

Thank you for considering contributing to Docen! This document will guide you through the contribution process.

Code of Conduct

This project follows the Contributor Covenant. By participating, you are expected to uphold this code.

Getting Started

1. Setup Development Environment

# Clone the repository
git clone https://github.com/docenjs/docen.git
cd docen

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run tests
pnpm test

2. Project Structure

docen/
  ├── packages/
  │   ├── docen/          # Core package
  │   ├── processors/     # Official processors
  │   └── cli/           # Command-line interface
  ├── docs/              # Documentation
  ├── examples/          # Usage examples
  └── tests/            # Test suites

Development Workflow

1. Creating Issues

Before starting work:

• Check existing issues and PRs
• Create a new issue describing the change
• Wait for issue to be approved/discussed

2. Making Changes

Follow these steps:

1. Create a new branch
2. Make your changes
3. Add tests
4. Update documentation
5. Run linting and tests
6. Submit PR

3. Coding Standards

We follow strict coding standards:

// Use TypeScript
// Follow ESLint rules
// Write JSDoc comments
// Use meaningful variable names
// Keep functions small and focused

4. Testing

All changes require tests:

// Unit tests for new features
describe("feature", () => {
  it("should work correctly", () => {
    // Test implementation
  });
});

// Integration tests where needed
// Performance tests for critical paths

Building Processors

1. Processor Structure

import { BaseProcessor } from "docen/core";

export class CustomProcessor extends BaseProcessor {
  name = "custom";
  supportedFormats = [".custom"];

  async read(input: Buffer): Promise<Document> {
    // Implementation
  }

  async write(document: Document): Promise<Buffer> {
    // Implementation
  }
}

2. Testing Processors

describe("CustomProcessor", () => {
  it("should read custom format", async () => {
    const processor = new CustomProcessor();
    const result = await processor.read(input);
    expect(result).toMatchSnapshot();
  });
});

Documentation

1. Code Documentation

Use JSDoc comments:

/**
 * Converts a document from one format to another.
 * @param input - Source document
 * @param output - Target path
 * @returns Promise resolving when complete
 */
async function convert(input: string, output: string): Promise<void> {
  // Implementation
}

2. README Updates

Keep documentation current:

• Update feature lists
• Add new examples
• Document breaking changes
• Update version information

Release Process

1. Version Bumping

Follow semver:

• MAJOR: Breaking changes
• MINOR: New features
• PATCH: Bug fixes

2. Changelog

Update CHANGELOG.md:

## [1.1.0] - 2024-03-20

### Added

- New feature X
- Support for Y

### Fixed

- Bug in Z
- Performance issue

Community

1. Getting Help

• GitHub Discussions

2. Reporting Issues

Include:

• Version information
• Environment details
• Minimal reproduction
• Expected behavior
• Actual behavior

Next Steps

• Review Core Concepts
• Check API Reference