Contributing to Antelopejs

Contributing Guide

This guide will help you contribute to Antelopejs, whether you're a developer, writer, or community member.

Ecosystem Overview

The Antelopejs ecosystem consists of two main repository groups:

Note: There is a process for migrating modules to the ajs-modules organization. Each module has its own maintainer but is supported by the broader community.

Ways to Contribute

Community Support

• Answer questions in GitHub Discussions
• Help with issue triage by reproducing reported bugs
• Share your solutions to common problems
• Provide feedback on new features and proposals

Reporting Issues

Before creating a new issue:

1. For bugs, follow our bug reporting guide
2. For feature requests, check existing issues and discussions
3. Submit module-specific ideas to the relevant repository
4. For broader ideas, start a discussion in the Ideas section

Documentation Improvements

Documentation is critical for user success:

• Fix typos or clarify existing content
• Add missing examples or code samples
• Improve organization or navigation
• Translate documentation to other languages

Pull Request Process

Before Starting

1. Bug fixes: Check if there's an existing issue
2. Features: Open a discussion first to align with project goals
3. Documentation: For typo fixes, consider combining multiple corrections

Development Workflow

1. Fork the repository to your GitHub account
2. Clone your fork to your local machine
3. Create a feature branch with a descriptive name
4. Make changes following the code standards
5. Write tests for new features or bug fixes
6. Ensure all tests pass locally
7. Submit your pull request

Commit Guidelines

We follow the Conventional Commits standard:

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

[optional body]

[optional footer]

Common types include:

• feat: A new feature
• fix: A bug fix
• docs: Documentation changes
• style: Formatting changes
• refactor: Code refactoring without functionality changes
• test: Adding or updating tests
• chore: Maintenance tasks

Examples:

feat(api): add support for custom headers
fix(auth): correct token validation logic
docs(readme): update installation instructions

Pull Request Guidelines

• Use a clear, descriptive title following commit conventions
• Reference related issues in the description (e.g., "Fixes #123")
• Keep each PR focused on a single task or feature
• Respond promptly to reviewer feedback

Decision Making Process

This flowchart guides our PR review process:

      
flowchart TB
  start([Pull Request Submitted])
  kind{What type of change?}
  documentation[Documentation Change]
  feature[New Feature]
  bugfix[Bug Fix]
  doc_review[Review for clarity and accuracy]
  feature_review[Assess necessity and implementation]
  bugfix_type{Is it a straightforward fix?}
  simple_fix[Verify fix and code quality]
  complex_fix[Review potential side effects]
  add_labels[Add priority labels]
  await_input[Await maintainer input]
  approve[Approve]
  merge[Merge when approved by 2+ team members]
  start --> kind
  kind --> documentation
  kind --> feature
  kind --> bugfix
  documentation --> doc_review
  doc_review --> approve
  feature --> feature_review
  feature_review --> await_input
  bugfix --> bugfix_type
  bugfix_type -->|Yes| simple_fix
  bugfix_type -->|No| complex_fix
  simple_fix --> approve
  complex_fix --> add_labels
  add_labels --> await_input
  await_input --> approve
  approve --> merge
  classDef process fill:#f9f9f9,stroke:#333,stroke-width:1px
  classDef decision fill:#e1f5fe,stroke:#0288d1,stroke-width:1px
  classDef endpoint fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
  class start,doc_review,feature_review,simple_fix,complex_fix,add_labels,await_input process
  class kind,bugfix_type decision
  class approve,merge endpoint

    

Creating Generic Interfaces

If you've built something useful with Antelopejs, consider turning it into a generic interface that others can implement:

Why Create Generic Interfaces?

• Ecosystem Growth: Generic interfaces allow multiple implementations to flourish
• Flexibility: Users can switch between implementations based on their needs
• Collaboration: Different developers can focus on specific implementations
• Standardization: Establishes common patterns across the ecosystem

From Feature to Interface

1. Identify functionality that could benefit from multiple implementations
2. Abstract the core behavior into a clear interface definition
3. Document the interface requirements thoroughly
4. Create a reference implementation as a module

Interface Best Practices

• Keep interfaces focused on a single responsibility
• Design with future extensibility in mind
• Provide detailed type definitions
• Include example usage in documentation
• Reference related interfaces when appropriate

For detailed guidance, refer to our Module documentation and Export Interfaces guide.

Proposing RFCs

For significant framework changes:

1. Start by implementing your idea as a module when possible
2. Open a discussion with code examples and rationale
3. If appropriate, your proposal will be marked as an RFC

RFC stages:

• rfc: active - Open for community feedback
• rfc: approved - Accepted by the core team
• rfc: ready to implement - Issue created for implementation
• rfc: shipped - Implemented in a release
• rfc: archived - Not approved but preserved for reference