feat: add comprehensive GitHub workflow and development tools

CONTRIBUTING.md

@@ -0,0 +1,403 @@
+# 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
+
+```bash
+# 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
+
+```bash
+chmod +x scripts/git-workflow.sh
+./scripts/git-workflow.sh
+```
+
+### Manual Workflow
+
+1. **Create Feature Branch**
+   ```bash
+   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**
+   ```bash
+   # 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**
+   ```bash
+   git add .
+   git commit -m "feat: describe your changes"
+   ```
+
+5. **Push and Create PR**
+   ```bash
+   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
+
+```python
+# 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
+
+```html
+<!-- 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
+
+```javascript
+// 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
+
+```python
+# 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
+
+```bash
+# 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:**
+   ```python
+   # In stiftung/models.py
+   PAGE_CHOICES = [
+       # ... existing choices
+       ('your_new_page', 'Your New Page'),
+   ]
+   ```
+
+2. **Add template tag to your template:**
+   ```html
+   {% load help_tags %}
+   {% help_box 'your_new_page' user %}
+   ```
+
+3. **Create migration and test:**
+   ```bash
+   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:**
+   ```bash
+   docker-compose exec web python manage.py makemigrations
+   ```
+
+2. **Review migration files before committing**
+
+3. **Test migrations on production-like data:**
+   ```bash
+   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
+
+```markdown
+**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
+
+```markdown
+**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.