Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
528 lines (406 loc) · 14.8 KB

CONTRIBUTING.md

File metadata and controls

528 lines (406 loc) · 14.8 KB

Contributing Guidelines 🤝

Thank you for your interest in contributing to our development documentation system! This document provides guidelines for contributing effectively and maintaining high standards.

📋 Table of Contents

🏛️ Code of Conduct

Our Standards

  • Professional Communication: Be respectful and constructive in all interactions
  • Inclusive Environment: Welcome contributors from all backgrounds and experience levels
  • Quality Focus: Maintain high standards for code and documentation quality
  • Collaborative Spirit: Work together to improve the project for everyone

Unacceptable Behavior

  • Harassment, discrimination, or offensive language
  • Spam, trolling, or disruptive behavior
  • Violation of intellectual property rights
  • Deliberate introduction of security vulnerabilities

🚀 Getting Started

Prerequisites

  • Git: Latest version for version control
  • Node.js: 18+ for development tools
  • Editor: VS Code with recommended extensions
  • Knowledge: Familiarity with the technology stack you're contributing to

Setup Instructions

  1. Fork the Repository

    # Fork on GitHub, then clone your fork
git clone https://github.com/your-username/docs.git
cd docs

  2. Install Dependencies

    npm install

  3. Set Up Pre-commit Hooks

    npm run setup-hooks

  4. Verify Setup

    npm run verify-setup

Development Environment

# Install recommended VS Code extensions
code --install-extension esbenp.prettier-vscode
code --install-extension dbaeumer.vscode-eslint
code --install-extension ms-vscode.vscode-typescript-next
code --install-extension christian-kohler.path-intellisense

🔄 Development Workflow

Branch Strategy

# Always start from main
git checkout main
git pull origin main

# Create feature branch
git checkout -b feat/your-feature-name

# Or for bug fixes
git checkout -b fix/your-bug-description

# For documentation
git checkout -b docs/your-doc-update

Branch Naming Convention

  • feat/ - New features
  • fix/ - Bug fixes
  • docs/ - Documentation updates
  • style/ - Code style changes
  • refactor/ - Code refactoring
  • test/ - Adding or updating tests
  • chore/ - Maintenance tasks
  • perf/ - Performance improvements
  • ci/ - CI/CD changes
  • build/ - Build system changes
  • revert/ - Reverting changes
  • deps/ - Dependency updates
  • security/ - Security-related changes

Examples

feat/testing): add comprehensive E2E testing guidelines
fix(typescript): resolve path alias configuration issues
docs(readme): update navigation with role-based sections
style(eslint): enforce absolute import patterns
refactor(security): improve JWT implementation
test(react): add component testing examples
chore(deps): update dependencies to latest versions
perf(bundle): optimize bundle size with tree shaking
ci(github): add automated security scanning
build(webpack): configure path aliases for all build tools
revert(typescript): revert to relative imports for compatibility
deps(security): update vulnerable dependencies
security(auth): implement rate limiting for login attempts

📝 Commit Message Standards

Conventional Commits Format

This project follows the Conventional Commits specification.

Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Type Categories

Type Description Example
feat New features feat(auth): add OAuth2 authentication
fix Bug fixes fix(api): resolve CORS configuration issue
docs Documentation docs(readme): update installation instructions
style Code style style(eslint): enforce consistent formatting
refactor Code refactoring refactor(components): extract reusable hooks
test Testing test(security): add authentication tests
chore Maintenance chore(deps): update dependencies
perf Performance perf(bundle): optimize webpack configuration
ci CI/CD ci(github): add automated testing workflow
build Build system build(webpack): configure path aliases
revert Revert changes revert(typescript): revert import changes
deps Dependencies deps(security): update vulnerable packages
security Security security(auth): implement rate limiting

Scope Examples

  • (auth) - Authentication related
  • (api) - API related
  • (docs) - Documentation
  • (typescript) - TypeScript specific
  • (react) - React specific
  • (testing) - Testing related
  • (security) - Security related
  • (performance) - Performance related
  • (build) - Build system
  • (ci) - CI/CD pipeline

Description Guidelines

  • Use imperative mood: "add" not "added" or "adds"
  • Don't capitalize first letter: "add authentication" not "Add authentication"
  • No period at the end: "add authentication" not "add authentication."
  • Keep it concise: Under 72 characters
  • Be specific: "add JWT authentication" not "add auth"

Body Guidelines

  • Explain what and why: Not how
  • Use imperative mood: "change" not "changed"
  • Include motivation: Why this change was made
  • Reference issues: "Closes #123" or "Fixes #456"

Footer Guidelines

  • Breaking changes: Start with BREAKING CHANGE:
  • Issue references: "Closes #123", "Fixes #456"
  • Co-authored-by: For multiple contributors

Examples

# Simple feature
feat(auth): add JWT authentication

# Feature with body
feat(api): add user management endpoints

Add comprehensive CRUD operations for user management including
create, read, update, and delete operations with proper validation
and error handling.

Closes #123

# Breaking change
feat(typescript)!: enforce absolute imports

BREAKING CHANGE: Relative imports are no longer allowed. All imports
must use absolute paths with @ alias.

Migration guide: docs/migration/v1.0.0.md

# Multiple issues
fix(security): prevent XSS attacks in user input

- Add input sanitization for all user inputs
- Implement DOMPurify for HTML content
- Add validation for email and URL fields

Fixes #456
Closes #789

# Co-authored commit
feat(testing): add comprehensive E2E test suite

Co-authored-by: John Doe <john@example.com>
Co-authored-by: Jane Smith <jane@example.com>

🔄 Pull Request Process

Before Submitting

  1. Update Documentation

    # Update relevant documentation
npm run docs:update

  2. Run Tests

    # Run all tests
npm test

# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:e2e

  3. Check Code Quality

    # Lint code
npm run lint

# Format code
npm run format

# Type check
npm run type-check

  4. Update Changelog

    # Add entry to CHANGELOG.md
# Follow the format in the existing changelog

Pull Request Template

## Description
Brief description of changes made.

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Security enhancement

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] E2E tests pass
- [ ] Manual testing completed
- [ ] Security testing completed

## Documentation
- [ ] Code is documented
- [ ] README is updated
- [ ] CHANGELOG is updated
- [ ] API documentation is updated

## Checklist
- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my own code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged and published

## Related Issues
Closes #123
Fixes #456

Review Process

  1. Automated Checks

    • All CI/CD checks pass
    • Code coverage meets requirements
    • Security scan passes
    • Performance benchmarks pass

  2. Manual Review

    • Code review completed
    • Security review completed
    • Documentation review completed
    • Testing review completed

  3. Approval Requirements

    • At least 2 approvals from maintainers
    • All automated checks pass
    • No security vulnerabilities
    • Documentation is complete and accurate

📚 Documentation Standards

Writing Guidelines

  • Clear and Concise: Write for the target audience
  • Comprehensive: Cover all necessary information
  • Accurate: Ensure all information is correct and up-to-date
  • Consistent: Follow established patterns and terminology
  • Accessible: Use clear language and proper formatting

Structure Guidelines

  • Use Markdown: All documentation should be in Markdown format
  • Include Examples: Provide practical code examples
  • Cross-Reference: Link to related documentation
  • Version Information: Include version compatibility notes
  • Migration Guides: Provide clear migration paths for breaking changes

Content Guidelines

  • Introduction: Explain what the document covers
  • Prerequisites: List any requirements or setup needed
  • Step-by-Step Instructions: Provide clear, numbered steps
  • Examples: Include practical, working examples
  • Troubleshooting: Address common issues and solutions
  • References: Link to additional resources

🧪 Testing Requirements

Test Coverage

  • Unit Tests: 80%+ coverage for critical paths
  • Integration Tests: All API endpoints and workflows
  • E2E Tests: Critical user journeys
  • Security Tests: Authentication, authorization, and input validation
  • Performance Tests: Load testing and performance benchmarks

Test Guidelines

  • Write Tests First: Follow TDD when possible
  • Meaningful Tests: Test behavior, not implementation
  • Isolated Tests: Each test should be independent
  • Descriptive Names: Use clear, descriptive test names
  • Proper Assertions: Use appropriate assertion methods

Test Examples

// Good test example
describe('UserService', () => {
  describe('createUser', () => {
    it('should create user with valid data', async () => {
      const userData = {
        name: 'John Doe',
        email: 'john@example.com',
        password: 'SecurePass123!'
      };

      const result = await UserService.createUser(userData);

      expect(result).toMatchObject({
        id: expect.any(String),
        name: userData.name,
        email: userData.email,
        createdAt: expect.any(Date)
      });
    });

    it('should throw error for invalid email', async () => {
      const userData = {
        name: 'John Doe',
        email: 'invalid-email',
        password: 'SecurePass123!'
      };

      await expect(UserService.createUser(userData))
        .rejects
        .toThrow('Invalid email address');
    });
  });
});

🔍 Review Process

Code Review Checklist

  • Functionality: Does the code work as intended?
  • Security: Are there any security vulnerabilities?
  • Performance: Are there any performance issues?
  • Maintainability: Is the code easy to understand and maintain?
  • Testing: Are there adequate tests?
  • Documentation: Is the code properly documented?
  • Standards: Does the code follow project standards?
  • Accessibility: Are accessibility requirements met?

Security Review Checklist

  • Input Validation: Are all inputs properly validated?
  • Authentication: Are authentication mechanisms secure?
  • Authorization: Are authorization checks in place?
  • Data Protection: Is sensitive data properly protected?
  • Error Handling: Do errors not expose sensitive information?
  • Dependencies: Are dependencies up-to-date and secure?

Documentation Review Checklist

  • Accuracy: Is all information correct and up-to-date?
  • Completeness: Are all necessary topics covered?
  • Clarity: Is the content clear and easy to understand?
  • Consistency: Does it follow established patterns?
  • Examples: Are there practical examples provided?
  • Links: Are all links working and relevant?

🚀 Release Process

Pre-Release Checklist

  • All tests pass
  • Documentation is updated
  • Changelog is updated
  • Security scan passes
  • Performance benchmarks pass
  • Code review is complete
  • Dependencies are up-to-date

Release Steps

  1. Create Release Branch

    git checkout -b release/v1.0.0

  2. Update Version

    npm version patch|minor|major

  3. Update Changelog

    # Move unreleased changes to new version
# Update release date

  4. Create Pull Request

    git push origin release/v1.0.0
# Create PR for review

  5. Merge and Tag

    git checkout main
git merge release/v1.0.0
git tag v1.0.0
git push origin main --tags

  6. Deploy

    npm run deploy

🤝 Getting Help

Communication Channels

  • Issues: Use GitHub issues for bug reports and feature requests
  • Discussions: Use GitHub discussions for questions and ideas
  • Security: Use security@example.com for security issues
  • Documentation: Use docs@example.com for documentation questions

Resources

Mentorship

  • New Contributors: Ask for help in discussions or issues
  • Code Reviews: Request reviews from experienced contributors
  • Pair Programming: Arrange pair programming sessions
  • Documentation: Help improve documentation for others

Thank you for contributing! 🎉

Your contributions help make this project better for everyone. We appreciate your time and effort in maintaining high standards and following these guidelines.

Last Updated: January 15, 2024
Maintainer: Development Standards Team