Skip to main content

Contributing Guidelines

Thank you for your interest in contributing to our development standards! This document outlines how to propose, discuss, and implement new standards or improvements to existing ones.

🎯 Purpose​

This repository serves as a living document for development standards and best practices. Our goal is to:

  • Maintain consistent development practices across teams and projects
  • Provide clear guidance for developers at all experience levels
  • Foster discussion and continuous improvement of our methodologies
  • Create reusable patterns that can be applied across different technology stacks

🤝 How to Contribute​

1. Types of Contributions​

We welcome several types of contributions:

📋 Standards Proposals

  • New coding conventions
  • Development workflow improvements
  • Architecture patterns
  • Tool recommendations

📚 Documentation Improvements

  • Clarifying existing guidelines
  • Adding examples and use cases
  • Fixing typos or formatting issues
  • Translating content

🛠️ Process Enhancements

  • Onboarding improvements
  • Review process optimizations
  • Template updates

💡 Discussion Topics

  • Challenge existing practices
  • Propose alternative approaches
  • Share experiences and lessons learned

2. Before You Start​

Check Existing Content

  • Review current standards to avoid duplication
  • Search existing issues and pull requests
  • Look for related discussions in team channels on Slack (#javascript)

Consider Scope and Impact

  • Will this apply to multiple projects/teams?
  • Does it align with our core principles?
  • Is it technology-stack agnostic when possible?

Gather Evidence

  • Industry best practices
  • Team pain points or feedback
  • Performance or security implications
  • Real-world examples

3. Contribution Workflow​

For Minor Changes (Documentation fixes, small clarifications)​

  1. Fork the repository
  2. Create a feature branch: fix/update-git-conventions
  3. Make your changes
  4. Test locally (run build, check links)
  5. Submit a pull request

For Major Changes (New standards, significant updates)​

  1. Open an Issue First

    • Use the "Standards Proposal" template
    • Describe the problem you're solving
    • Outline your proposed solution
    • Tag relevant team members

  2. Gather Feedback

    • Allow time for team discussion (minimum 1 week)
    • Address questions and concerns
    • Refine your proposal based on input

  3. Create Implementation

    • Fork and create feature branch
    • Follow the agreed approach from discussion
    • Include examples and rationale
    • Add to appropriate documentation sections

  4. Submit Pull Request

    • Reference the original issue
    • Summarize changes and decisions made
    • Request review from relevant stakeholders

📝 Writing Standards​

Content Structure​

Standard Format:

# [Standard Name]

## Overview

Brief description of what this standard covers and why it exists.

## When to Apply

Specific situations where this standard should be used.

## Guidelines

Clear, actionable rules and recommendations.

## Examples

Concrete examples showing correct implementation.

## Anti-patterns

Common mistakes to avoid.

## Rationale

Why these decisions were made (optional but helpful).

## Related Standards

Links to connected or dependent standards.

Writing Style​

Be Clear and Concise

  • Use simple, direct language
  • Avoid jargon when possible
  • Define technical terms when necessary

Be Specific

  • Provide concrete examples
  • Use "should" for recommendations, "must" for requirements
  • Include edge cases and exceptions

Be Technology Agnostic (When Possible)

  • Focus on principles over specific tools
  • Explain concepts that transfer across stacks
  • Note technology-specific variations separately

Be Actionable

  • Include step-by-step instructions
  • Provide templates and boilerplate
  • Link to relevant tools and resources

Code Examples​

  • Use consistent formatting and syntax highlighting
  • Include both "good" and "bad" examples when helpful
  • Provide context for why examples work
  • Keep examples simple but realistic

🔄 Review Process​

Peer Review​

Major changes require:

  • Technical Review: Accuracy and feasibility
  • Editorial Review: Clarity and consistency
  • Stakeholder Approval: Team lead or designated approver

Approval Criteria​

Changes are approved when they:

  • Solve a real problem or improve current practices
  • Are well-documented with clear examples
  • Have been discussed and refined based on feedback
  • Don't conflict with existing standards (or explicitly supersede them)
  • Follow our writing and formatting guidelines

🏷️ Issue and PR Labels​

Use these labels to categorize your contributions:

Type:

  • enhancement - New standards or major improvements
  • documentation - Content updates and clarifications
  • bug - Fixes to existing content
  • discussion - Topics for team consideration

Priority:

  • critical - Blocking issues or urgent updates
  • high - Important improvements
  • medium - General enhancements
  • low - Nice-to-have changes

Scope:

  • standards - Core development practices
  • onboarding - New team member resources
  • process - Workflow and methodology
  • tooling - Development tools and setup

Status:

  • needs-discussion - Requires team input
  • ready-for-review - Complete and awaiting approval
  • blocked - Cannot proceed without external dependency

📋 Templates​

Standards Proposal Issue Template​

## Problem Statement

What issue does this standard address?

## Proposed Solution

High-level approach to solving the problem.

## Scope

- Which projects/teams would this affect?
- What technology stacks does this apply to?

## Implementation Plan

- [ ] Research and draft standard
- [ ] Gather team feedback
- [ ] Create examples and documentation
- [ ] Update related standards if needed

## Success Criteria

How will we know this standard is effective?

## Additional Context

Links, references, or background information.

Pull Request Template​

## Changes Made

Brief summary of what was added, changed, or removed.

## Related Issue

Fixes #[issue-number] (if applicable)

## Type of Change

- [ ] New standard
- [ ] Documentation update
- [ ] Bug fix
- [ ] Process improvement

## Checklist

- [ ] Content follows writing guidelines
- [ ] Examples are clear and correct
- [ ] Links are valid and working
- [ ] Spelling and grammar checked
- [ ] Related documentation updated

🚀 Getting Started​

Ready to contribute? Here are some good first steps:

  1. Browse Current Issues: Look for good-first-issue labels
  2. Identify Gaps: What standards are missing from your daily work?
  3. Start Small: Fix typos, improve examples, or clarify confusing sections
  4. Join Discussions: Participate in existing standards proposals

💬 Questions and Support​

Need Help?

  • Open an issue with the question label
  • Reach out in team chat channels on Slack (#javascript)
  • Contact the standards maintainers directly

Want to Discuss Ideas?

  • Start with an informal chat in team channels
  • Open a discussion issue before creating detailed proposals
  • Join regular standards review meetings

🤖 AI Assistant Guidelines Review

If you're using Claude Code or similar AI assistants, you can ask them to review your contributions against our guidelines:

  • For Content Review: Ask "Does this follow the project's markdown style guide and contributing guidelines?"
  • For Standards Compliance: Request "Please check if this contribution follows DECODE's development standards"
  • For Structure Review: Ask "Is this organized according to the project's documentation structure?"

Important: When working with AI assistants on this project, always include this instruction:

"Please also update the TODO list and commit the changes when you're done."

This ensures that:

  • The project TODO list stays current
  • Changes are properly committed with appropriate messages
  • Project memory (CLAUDE.md) reflects the latest status
  • Other team members can see progress and current priorities

The AI assistant has access to our complete style guide, contributing guidelines, and organizational standards to help ensure consistency.

Remember: Great standards come from shared experiences and collaborative refinement. Your perspective and expertise make our practices stronger!