|
|
@@ -1,270 +0,0 @@
|
|
|
-# 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](#code-of-conduct)
|
|
|
-- [How to Contribute](#how-to-contribute)
|
|
|
-- [CLI Development](#cli-development)
|
|
|
-- [Template Contributions](#template-contributions)
|
|
|
-- [Development Setup](#development-setup)
|
|
|
-- [Code Standards](#code-standards)
|
|
|
-- [Testing Guidelines](#testing-guidelines)
|
|
|
-- [Pull Request Process](#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](https://christianlempa.de/discord)
|
|
|
-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](../../wiki/Developers) 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:
|
|
|
-```bash
|
|
|
-git clone https://github.com/ChristianLempa/boilerplates.git
|
|
|
-cd boilerplates
|
|
|
-```
|
|
|
-
|
|
|
-2. Create a virtual environment:
|
|
|
-```bash
|
|
|
-python3 -m venv venv
|
|
|
-source venv/bin/activate # On Windows: venv\Scripts\activate
|
|
|
-```
|
|
|
-
|
|
|
-3. Install dependencies:
|
|
|
-```bash
|
|
|
-pip install -e .
|
|
|
-```
|
|
|
-
|
|
|
-4. Run the CLI in development mode:
|
|
|
-```bash
|
|
|
-python3 -m cli --help
|
|
|
-```
|
|
|
-
|
|
|
-### Development Commands
|
|
|
-
|
|
|
-```bash
|
|
|
-# 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:
|
|
|
-
|
|
|
-```python
|
|
|
-# 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
|
|
|
-
|
|
|
-```python
|
|
|
-# 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:
|
|
|
-
|
|
|
-```python
|
|
|
-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:**
|
|
|
-
|
|
|
-```bash
|
|
|
-# YAML files
|
|
|
-yamllint library/
|
|
|
-
|
|
|
-# Python code - check and auto-fix
|
|
|
-ruff check --fix .
|
|
|
-
|
|
|
-# Python code - format
|
|
|
-ruff format .
|
|
|
-```
|
|
|
-
|
|
|
-### Validation Commands
|
|
|
-
|
|
|
-```bash
|
|
|
-# 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:
|
|
|
-
|
|
|
-```bash
|
|
|
-# 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](../../wiki) for documentation
|
|
|
-- Join [Discord](https://christianlempa.de/discord) for discussions
|
|
|
-- Open an issue for bugs or feature requests
|
|
|
-- Watch [YouTube tutorials](https://www.youtube.com/@christianlempa)
|
|
|
-
|
|
|
-## License
|
|
|
-
|
|
|
-By contributing, you agree that your contributions will be licensed under the same license as the project.
|
|
|
-
|
|
|
-Thank you for contributing to Boilerplates!
|