boilerplates/CONTRIBUTING.md

Contributing to Boilerplates

Thank you for your interest in contributing to the Boilerplates project! This document provides guidelines and instructions for contributing.

Table of Contents

• Code of Conduct
• How to Contribute
• CLI Development
• Template Contributions
• Development Setup
• Code Standards
• Testing Guidelines
• Pull Request Process

Code of Conduct

Be respectful and constructive in all interactions. We're here to build great tools together.

How to Contribute

CLI Development

IMPORTANT: Any changes to the CLI application (cli/ directory) require coordination.

Before making CLI changes:

1. Join the Discord server
2. Reach out to discuss your proposed changes
3. Wait for approval before opening a PR

Rationale: The CLI architecture is complex and tightly integrated. Coordinating changes ensures consistency and prevents conflicts.

Template Contributions

Template contributions are welcome and encouraged! You can:

• Add new templates to library/
• Improve existing templates
• Fix bugs in templates
• Update template documentation

Process:

1. Read the Developer Documentation in the Wiki
2. Create a new branch: feature/###-template-name or problem/###-fix-description
3. Add or modify templates following the structure in library/
4. Test your template thoroughly
5. Open a pull request

No prior approval needed for template contributions, but feel free to open an issue first to discuss larger changes.

Development Setup

Prerequisites

• Python 3.10 or higher
• Git
• pipx (recommended) or pip

Installation

1. Clone the repository:

git clone https://github.com/ChristianLempa/boilerplates.git
cd boilerplates

2. Create a virtual environment:

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -e .

4. Run the CLI in development mode:

python3 -m cli --help

Development Commands

# Run CLI with debug logging
python3 -m cli --log-level DEBUG compose list

# Test template generation
python3 -m cli compose generate template-name --dry-run

# Validate templates
python3 -m cli compose validate

Code Standards

Python Style Guide

• Follow PEP 8 conventions
• Use 2-space indentation (project standard)
• Maximum line length: 100 characters
• Use type hints where appropriate

Naming Conventions

• Files: lowercase with underscores (variable_display.py)
• Classes: PascalCase (VariableCollection, DisplayManager)
• Functions/Methods: snake_case (render_template, get_spec)
• Constants: UPPER_SNAKE_CASE (DEFAULT_TIMEOUT, MAX_RETRIES)
• Private methods: prefix with underscore (_parse_section)

Comment Anchors

Use standardized comment anchors for important notes:

# TODO: Implement feature X
# FIXME: Bug in validation logic
# NOTE: This is a workaround for issue #123
# LINK: https://docs.python.org/3/library/typing.html

DisplayManager Usage

CRITICAL RULE:

• NEVER use console.print() outside of display manager classes
• NEVER import Console from rich.console except in display manager classes
• ALWAYS use display.display_*() methods for ALL output

# GOOD
display = DisplayManager()
display.display_success("Template generated successfully")

# BAD
from rich.console import Console
console = Console()
console.print("Template generated")  # Don't do this!

Docstrings

Use docstrings for all public classes and methods:

def render_template(self, template: Template, template_id: str) -> None:
  """Render a complete template display.
  
  Args:
    template: The Template object to render
    template_id: The template identifier
  """
  pass

Testing Guidelines

Linting and Formatting

REQUIRED before committing:

# YAML files
yamllint library/

# Python code - check and auto-fix
ruff check --fix .

# Python code - format
ruff format .

Validation Commands

# Validate all templates
python3 -m cli compose validate

# Validate specific template
python3 -m cli compose validate template-name

# Validate with semantic checks
python3 -m cli compose validate --semantic

Manual Testing

Before submitting a PR, test your changes:

# Test template generation
python3 -m cli compose generate your-template --dry-run

# Test interactive mode
python3 -m cli compose generate your-template

# Test non-interactive mode
python3 -m cli compose generate your-template output-dir \
  --var service_name=test \
  --no-interactive

Pull Request Process

Branch Naming

• Features: feature/###-description (e.g., feature/1234-add-nginx-template)
• Bug fixes: problem/###-description (e.g., problem/1235-fix-validation)

Commit Messages

Follow the format: type(scope): subject

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• refactor: Code refactoring
• test: Adding tests
• chore: Maintenance tasks

Examples:

feat(compose): add nginx template
fix(display): correct variable rendering for enum types
docs(wiki): update installation instructions
refactor(template): simplify Jinja2 rendering logic

PR Checklist

Before submitting a pull request:

• Code follows style guidelines (run ruff check and ruff format)
• YAML files pass yamllint
• All templates validate successfully
• Changes are tested manually
• Commit messages follow conventions
• PR description explains the changes
• Related issues are referenced (e.g., "Closes #1234")

PR Review

• PRs require approval before merging
• Address review comments promptly
• Keep PRs focused and reasonably sized
• Squash commits if requested

Issue Labels

When creating issues, use appropriate labels:

• feature - New feature requests
• problem - Bug reports
• discussion - General discussions
• question - Questions about usage
• documentation - Documentation improvements

Getting Help

• Check the Wiki for documentation
• Join Discord for discussions
• Open an issue for bugs or feature requests
• Watch YouTube tutorials

License

By contributing, you agree that your contributions will be licensed under the same license as the project.

Thank you for contributing to Boilerplates!