404 lines
9.0 KiB
Markdown
404 lines
9.0 KiB
Markdown
# 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.
|