Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
101 lines (72 loc) · 2.69 KB

CONTRIBUTING.md

File metadata and controls

101 lines (72 loc) · 2.69 KB

Contributing to Coding Standards Handbook

Thank you for helping maintain and improve this handbook!

Philosophy

This handbook defines principles and standards with precision and clarity. Contributions should be:

  • Clear - Written in plain, precise language
  • Structured - Organized logically with consistent format
  • Precise - Specific and unambiguous
  • Non-repetitive - No unnecessary duplication
  • Evidence-based - Grounded in practice or principle

Entry Structure

Each handbook entry should include:

# Topic Title

## Definition
What is this exactly?

## Principle
What's the underlying principle?

## Explanation
Why does this matter? How does it work?

## Example
A concrete example or reference implementation

## Anti-pattern
What NOT to do in this area

## Related Concepts
Links to related handbook entries

How to Contribute

  1. Fork the repository
  2. Review existing entries for consistency
  3. Create a branch for your contribution
  4. Add or update entries in appropriate folders
  5. Follow the structure above
  6. Verify uniqueness - no repetition of existing content
  7. Commit with a clear message
  8. Push to your fork
  9. Create a Pull Request with explanation

Folder Guidelines

  • principles/ - Fundamental concepts and core ideas
  • standards/ - Quality specifications and requirements
  • guidelines/ - Recommended practices and how-to guidance
  • definitions/ - Precise terminology definitions
  • patterns/ - Proven, repeatable solutions
  • anti-patterns/ - Common mistakes and what to avoid
  • examples/ - Reference implementations and case studies
  • checklists/ - Verification guides and evaluation rubrics
  • references/ - Cited sources and additional reading
  • assets/ - Visual materials and diagrams

File Naming Convention

Use descriptive, lowercase filenames with hyphens:

api-versioning-strategy.md
microservice-communication-patterns.md
code-review-standards.md

Quality Standards

  • Content should be accurate and verifiable
  • Examples should be realistic and representative
  • Anti-patterns should include explanation of why to avoid
  • External references should be properly cited
  • No promotional or self-serving content
  • Respectful of different valid approaches

Review Process

All contributions will be reviewed for:

  1. Accuracy and precision
  2. Consistency with existing material
  3. Clarity and structure
  4. Relevance to handbook purpose
  5. Quality and completeness

We may request clarification or suggest refinements before merging.

License

All contributions are shared under the same license as the repository (MIT).

Thank you for helping maintain these essential standards!