Contributing Guide

This guide explains how to contribute to our engineering standards and documentation.

Contribution Process

1. Types of Contributions

We welcome various types of contributions:

• Documentation improvements
• New standards proposals
• Template updates
• Bug fixes
• Tool configurations
• Best practices

2. Before Contributing

Preparation

1. Read existing documentation
2. Check for related issues/discussions
3. Discuss major changes in #engineering channel
4. Use our templates

Making Changes

1. Branch Naming

Follow our branch naming convention:

# Format: type/description
docs/update-git-standards
feature/add-react-template
fix/correct-docker-setup

2. Commit Messages

We use Conventional Commits:

# Format: type(scope): description
docs(git): update branching strategy
feat(templates): add Vue.js template
fix(setup): correct Docker installation steps

3. Documentation Style

Markdown Guidelines

• Use ATX-style headers (# for h1, ## for h2)
• Include a single H1 header per file
• Use code blocks with language specification
• Add alt text to images
• Use relative links

Example:

# Component Title

## Overview

This section explains...

### Code Example

```typescript
function example(): void {
    console.log("Hello");
}

See the standards overview

#### Admonitions

Use admonitions for special content:

!!! note "Note"
    Important information that users should know about.

!!! warning "Warning"
    Critical information about potential issues.

!!! tip "Tip"
    Helpful advice and suggestions.

### 4. Pull Request Process

1. Create a new branch
2. Make your changes
3. Test locally using MkDocs
4. Submit a pull request
5. Address review feedback

#### PR Template

Your PR description should include:

```markdown
## Description
Brief description of changes

## Type of Change
- [ ] Documentation update
- [ ] New feature
- [ ] Bug fix
- [ ] Template update

## Checklist
- [ ] Updated documentation
- [ ] Tested locally
- [ ] Followed style guide
- [ ] Added examples (if applicable)

Review Process

1. Code Review Guidelines

As a reviewer:

• Check for technical accuracy
• Verify documentation clarity
• Ensure style guide compliance
• Test examples if provided
• Provide constructive feedback

As an author:

• Respond to feedback promptly
• Make requested changes
• Ask for clarification if needed
• Update based on discussions

2. Documentation Review

Check for:

• Technical accuracy
• Clear explanations
• Proper formatting
• Working links
• Code example validity
• Grammar and spelling

Style Guide

1. Writing Style

• Be clear and concise
• Use active voice
• Include examples
• Explain acronyms
• Keep paragraphs focused

2. Code Examples

• Include language specification
• Use meaningful variable names
• Add comments for clarity
• Show complete, working examples
• Follow our coding standards

3. File Organization

• Use consistent naming
• Group related content
• Maintain clear hierarchy
• Include README files
• Follow template structure

Testing Changes

1. Local Testing

# Install MkDocs and dependencies
pip install -r requirements.txt

# Serve documentation locally
mkdocs serve

# Build documentation
mkdocs build

2. Link Checking

• Verify internal links
• Check external references
• Test navigation flow
• Validate code examples

Getting Help

If you need assistance:

1. Check existing documentation
2. Ask in #engineering channel
3. Contact team leads
4. Open an issue for discussion

Best Practices

1. Documentation:

   • Keep it up to date
   • Be comprehensive
   • Include examples
   • Use clear language

2. Changes:

   • Make atomic commits
   • Test thoroughly
   • Update related docs
   • Follow templates

3. Communication:

   • Be responsive
   • Ask questions
   • Share knowledge
   • Help others