Contribution Guidelines for scorm-again

Thank you for your interest in contributing to scorm-again! This document provides detailed guidelines for contributing to the project, including code standards, pull request process, and best practices.

Table of Contents

1. Types of Contributions
2. Code Standards
3. Documentation Standards
4. Testing Requirements
5. Pull Request Process
6. Community Guidelines

Types of Contributions

We welcome various types of contributions to scorm-again:

Code Contributions

• Bug fixes
• Performance improvements
• New features
• Refactoring for better maintainability
• Dependency updates

Documentation Contributions

• API documentation improvements
• Usage examples
• Tutorials
• Fixing typos or clarifying existing documentation

Testing Contributions

• Adding test cases for existing functionality
• Improving test coverage
• Creating test utilities
• Adding integration tests

Other Contributions

• Reporting bugs
• Suggesting enhancements
• Helping with issue triage
• Answering questions in discussions or issues

Code Standards

scorm-again follows strict coding standards to maintain a high-quality, consistent codebase:

TypeScript Guidelines

• Follow the TypeScript style guide in typescript_guidelines.md
• Use TypeScript's strict mode
• Provide explicit types for all parameters and return values
• Avoid using any type when possible
• Use interfaces for object shapes that will be implemented by classes
• Use type aliases for union types, intersection types, and complex types

Naming Conventions

• Use PascalCase for class names, interfaces, and type aliases
• Use camelCase for variables, functions, and method names
• Use UPPER_SNAKE_CASE for constants and enum values
• Prefix interfaces with I when they define a contract for a class (e.g., IBaseAPI)
• Prefix private class members with an underscore (e.g., _checkObjectHasProperty)

Code Organization

• Keep files focused on a single responsibility
• Aim to keep files under 500 lines
• Organize imports as specified in the style guide
• Use barrel files (index.ts) to simplify imports from directories with multiple exports

Error Handling

• Use custom error classes for domain-specific errors
• Throw specific error types rather than generic Error objects
• Handle errors at the appropriate level of abstraction
• Provide meaningful error messages

Documentation Standards

Good documentation is crucial for the usability of scorm-again:

Code Documentation

• Use JSDoc comments for all public methods and classes
• Include parameter descriptions, return types, and examples in JSDoc comments
• Document complex algorithms and business logic with clear comments
• Keep comments up-to-date with code changes

API Documentation

• Provide clear examples for each API
• Document common use cases and patterns
• Include troubleshooting information for common issues
• Use consistent terminology throughout documentation

README and Other Markdown Files

• Use clear, concise language
• Structure documents with appropriate headings
• Include a table of contents for longer documents
• Use code blocks with appropriate syntax highlighting

Testing Requirements

Testing is a critical part of maintaining scorm-again's quality:

Test Coverage

• All new code should have corresponding tests
• Aim for high test coverage, especially for critical functionality
• Test both success and error cases
• Test edge cases and boundary conditions

Test Organization

• Organize tests to mirror the source code structure
• Use descriptive test names that explain the expected behavior
• Follow the Arrange-Act-Assert pattern in tests
• Keep tests independent of each other

Running Tests

• Ensure all tests pass before submitting a pull request:

  npm run test:min

• Check test coverage when adding new features:

  npm run test:coverage

Test-Only Contributions

• Test-only contributions are welcome and encouraged
• Focus on improving coverage for critical or complex code
• Add tests for edge cases and error conditions
• Improve existing tests for clarity and completeness

Pull Request Process

Follow these steps to submit a pull request:

1. Fork and Clone: Fork the repository and clone it locally
2. Branch: Create a feature branch for your changes
3. Develop: Make your changes following the code standards
4. Test: Ensure all tests pass and add new tests as needed
5. Document: Update documentation to reflect your changes
6. Format: Run Prettier and ESLint to ensure code style compliance
7. Commit: Use clear, descriptive commit messages
8. Push: Push your changes to your fork
9. Pull Request: Submit a pull request with a clear description of your changes

Pull Request Description

Include the following in your pull request description:

• What the changes do
• Why the changes are needed
• Any notable implementation details
• References to related issues
• Any manual testing you've performed
• Any potential concerns or areas for reviewer focus

Review Process

• At least one maintainer will review your pull request
• Automated tests will run on your pull request
• You may be asked to make changes based on feedback
• Once approved, your changes will be merged

Community Guidelines

scorm-again is a community project, and we value respectful and constructive interaction:

Communication

• Be respectful and considerate in all communications
• Provide constructive feedback
• Be open to receiving feedback on your contributions
• Ask questions if something is unclear

Issue Reporting

When reporting issues:

• Use a clear, descriptive title
• Provide detailed steps to reproduce the issue
• Include relevant information about your environment
• Mention any workarounds you've discovered
• Suggest a fix if you have ideas

Feature Requests

When suggesting features:

• Clearly describe the problem the feature would solve
• Explain how the feature would benefit users
• Consider potential implementation approaches
• Be open to discussion about alternatives

By following these guidelines, you'll help maintain scorm-again as a high-quality, well-documented, and well-tested library that serves its users effectively.

Thank you for contributing to scorm-again!