stiftung-management-system/CONTRIBUTING.md

Contributing to Stiftung Application

Thank you for your interest in contributing! This guide will help you get started with development and ensure consistency across the project.

🚀 Quick Start

1. Development Environment Setup

# Clone the repository
git clone https://github.com/yourusername/stiftung-starter.git
cd stiftung-starter

# Run setup script
chmod +x scripts/dev-setup.sh
./scripts/dev-setup.sh

# Or manual setup:
cp env-template.txt .env
docker-compose up -d
docker-compose exec web python manage.py migrate
docker-compose exec web python manage.py createsuperuser

2. Verify Installation

• Application: http://localhost:8000
• Admin: http://localhost:8000/admin/
• HelpBox Admin: http://localhost:8000/help-box/admin/

🔄 Development Workflow

Using the Git Workflow Helper

chmod +x scripts/git-workflow.sh
./scripts/git-workflow.sh

Manual Workflow

1. Create Feature Branch

   git checkout main
   git pull origin main
   git checkout -b feature/your-feature-name
   

2. Make Changes

   • Follow coding standards (see below)
   • Add tests for new functionality
   • Update documentation if needed

3. Test Your Changes

   # Run tests
   docker-compose exec web python manage.py test
   
   # Check Django configuration
   docker-compose exec web python manage.py check
   
   # Test migrations
   docker-compose exec web python manage.py migrate --dry-run
   

4. Commit Changes

   git add .
   git commit -m "feat: describe your changes"
   

5. Push and Create PR

   git push origin feature/your-feature-name
   # Create Pull Request on GitHub
   

📝 Coding Standards

Python/Django Code

• PEP 8 compliance: Use black and flake8
• Import sorting: Use isort
• Docstrings: Document all classes and methods
• Type hints: Use type annotations where possible

# Example: Good code style
from typing import Optional, List
from django.db import models

class HelpBox(models.Model):
    """Editable help boxes with Markdown support."""
    
    title: str = models.CharField(max_length=200)
    content: str = models.TextField()
    
    def get_rendered_content(self) -> str:
        """Render Markdown content to HTML."""
        return markdown.markdown(self.content)
    
    @classmethod
    def get_help_for_page(cls, page_key: str) -> Optional['HelpBox']:
        """Get active help box for a specific page."""
        return cls.objects.filter(
            page_key=page_key, 
            is_active=True
        ).first()

HTML/Templates

• Bootstrap 5: Use consistent Bootstrap classes
• Template inheritance: Extend base.html
• Template tags: Create reusable components
• Accessibility: Include ARIA labels and alt text

<!-- Example: Good template structure -->
{% extends "base.html" %}
{% load help_tags %}

{% block content %}
<div class="container-fluid">
    <div class="row">
        <div class="col-lg-8">
            <!-- Main content -->
            <form method="post">
                {% csrf_token %}
                {{ form.as_p }}
                <button type="submit" class="btn btn-primary">Save</button>
            </form>
        </div>
        <div class="col-lg-4">
            <!-- Help box sidebar -->
            {% help_box 'page_key' user %}
        </div>
    </div>
</div>
{% endblock %}

JavaScript

• ES6+: Use modern JavaScript features
• No jQuery: Use vanilla JS or minimal libraries
• Accessibility: Support keyboard navigation

// Example: Good JavaScript structure
class HelpBoxEditor {
    constructor(elementId) {
        this.element = document.getElementById(elementId);
        this.init();
    }
    
    init() {
        this.element.addEventListener('click', this.handleEdit.bind(this));
    }
    
    handleEdit(event) {
        // Implementation
    }
}

🧪 Testing

Writing Tests

# Example: Test structure
from django.test import TestCase, Client
from django.contrib.auth import get_user_model
from stiftung.models import HelpBox

class HelpBoxTestCase(TestCase):
    def setUp(self):
        self.user = get_user_model().objects.create_user(
            username='testuser',
            password='testpass'
        )
        self.client = Client()
    
    def test_help_box_creation(self):
        """Test help box can be created."""
        help_box = HelpBox.objects.create(
            page_key='test_page',
            title='Test Help',
            content='# Test Content',
            created_by=self.user
        )
        self.assertEqual(help_box.title, 'Test Help')
    
    def test_help_box_rendering(self):
        """Test Markdown content is rendered correctly."""
        # Implementation

Running Tests

# Run all tests
docker-compose exec web python manage.py test

# Run specific test
docker-compose exec web python manage.py test stiftung.tests.test_helpbox

# Run with coverage
docker-compose exec web coverage run manage.py test
docker-compose exec web coverage report

📦 New Feature Development

Adding a New Model

1. Create model in stiftung/models.py
2. Add to Django admin in stiftung/admin.py
3. Create and run migrations
4. Add views in stiftung/views.py
5. Create templates
6. Add URL patterns
7. Write tests
8. Update documentation

Adding HelpBox Support to New Pages

1. Add page key to model choices:

   # In stiftung/models.py
   PAGE_CHOICES = [
       # ... existing choices
       ('your_new_page', 'Your New Page'),
   ]
   

2. Add template tag to your template:

   {% load help_tags %}
   {% help_box 'your_new_page' user %}
   

3. Create migration and test:

   docker-compose exec web python manage.py makemigrations
   docker-compose exec web python manage.py migrate
   

🎨 UI/UX Guidelines

Bootstrap Usage

• Use Bootstrap 5 utility classes
• Follow responsive design principles
• Maintain consistent spacing (mb-3, p-4, etc.)
• Use semantic HTML elements

Color Scheme

• Primary: Bootstrap primary blue
• Success: Bootstrap success green
• Warning: Bootstrap warning yellow
• Danger: Bootstrap danger red

Icons

• Use Bootstrap Icons or Font Awesome
• Consistent icon usage across features
• Include alt text for accessibility

📊 Database Changes

Migration Best Practices

1. Always create migrations:

   docker-compose exec web python manage.py makemigrations
   

2. Review migration files before committing

3. Test migrations on production-like data:

   docker-compose exec web python manage.py migrate --dry-run
   

4. Provide data migration scripts when needed

Model Changes

• Use descriptive field names
• Add help_text for complex fields
• Consider backward compatibility
• Document breaking changes

🚢 Deployment Considerations

Production Checklist

• All tests pass
• Migrations run successfully
• Static files collect properly
• Environment variables configured
• Security settings reviewed
• Performance impact assessed

Docker Best Practices

• Keep Dockerfile lean
• Use multi-stage builds when possible
• Don't include secrets in images
• Use .dockerignore effectively

📖 Documentation

Code Documentation

• Document all public methods
• Include usage examples
• Explain complex business logic
• Update docstrings when changing behavior

User Documentation

• Update README for new features
• Add screenshots for UI changes
• Document configuration options
• Provide troubleshooting guides

🐛 Bug Reports

Bug Report Template

**Describe the bug**
A clear description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. See error

**Expected behavior**
What you expected to happen.

**Screenshots**
If applicable, add screenshots.

**Environment:**
- OS: [e.g. Windows 10]
- Browser: [e.g. Chrome 96]
- Version: [e.g. v2.0.0]

**Additional context**
Any other context about the problem.

🔍 Code Review Guidelines

For Authors

• Keep PRs focused and small
• Write descriptive commit messages
• Test thoroughly before submitting
• Update documentation as needed

For Reviewers

• Review for functionality, security, and performance
• Check code style and conventions
• Verify tests are adequate
• Provide constructive feedback

🎯 Feature Requests

Feature Request Template

**Is your feature request related to a problem?**
A clear description of what the problem is.

**Describe the solution you'd like**
A clear description of what you want to happen.

**Describe alternatives you've considered**
Other solutions you've considered.

**Additional context**
Screenshots, mockups, or examples.

💬 Getting Help

• Create GitHub Issues for bugs
• Use GitHub Discussions for questions
• Check existing documentation first
• Provide minimal reproduction examples

📜 License

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