Contributing to Trunk8¶

Thank you for your interest in contributing to Trunk8! This guide will help you get started with contributing to the project.

Code of Conduct¶

By participating in this project, you agree to abide by our Code of Conduct:

Be respectful and inclusive
Welcome newcomers and help them get started
Focus on constructive criticism
Accept feedback gracefully
Prioritize the community's best interests

Ways to Contribute¶

Reporting Bugs¶

Found a bug? Please help us fix it!

Check existing issues first to avoid duplicates
Create a new issue with:
- Clear, descriptive title
- Steps to reproduce
- Expected vs actual behavior
- System information (Python version, OS, etc.)
- Error messages or logs

Example bug report:

**Description:**
Links with special characters in markdown content fail to render.

**Steps to reproduce:**
1. Create a markdown link
2. Add content with `<script>` tags
3. Access the link

**Expected:** Markdown renders with escaped HTML
**Actual:** Page shows error 500

**Environment:**
- Python 3.12.1
- macOS 14.0
- Firefox 120.0

Suggesting Features¶

Have an idea for improvement?

Check existing issues and discussions
Open a discussion to gauge interest
Create a feature request with:
- Use case description
- Proposed solution
- Alternative approaches
- Mockups or examples (if applicable)

Contributing Code¶

Ready to code? Great! Here's how:

1. Fork and Clone¶

# Fork on GitHub, then:
git clone https://github.com/YOUR-USERNAME/trunk8.git
cd trunk8
git remote add upstream https://github.com/lancereinsmith/trunk8.git

2. Set Up Development Environment¶

# Install uv (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
uv sync --extra dev

# Activate environment
source .venv/bin/activate

3. Create a Branch¶

# Update main branch
git checkout main
git pull upstream main

# Create feature branch
git checkout -b feature/your-feature-name

Branch naming conventions:

feature/ - New features
fix/ - Bug fixes
docs/ - Documentation updates
refactor/ - Code refactoring
test/ - Test additions/improvements

4. Make Your Changes¶

Follow these guidelines:

Code Style¶

Follow PEP 8
Use type hints
Add docstrings (Google style)
Keep functions focused and small
Use meaningful variable names

Example:

from typing import Optional, Dict, Any

def create_link(
    short_code: str, 
    link_data: Dict[str, Any]
) -> Optional[Link]:
    """
    Create a new link with the given short code and data.

    Args:
        short_code: Unique identifier for the link.
        link_data: Dictionary containing link type and properties.

    Returns:
        Link object if successful, None if short code exists.

    Raises:
        ValueError: If link_data is invalid.
    """
    # Implementation

Testing¶

Add tests for new functionality:

# tests/test_links.py
def test_create_link_with_expiration():
    """Test creating a link with expiration date."""
    link_data = {
        'type': 'redirect',
        'url': 'https://example.com',
        'expiration_date': '2024-12-31T23:59:59'
    }
    link = Link('test', link_data)
    assert not link.is_expired

Run tests:

pytest
pytest --cov=app  # With coverage

Documentation¶

Update docstrings
Add/update user documentation
Include examples
Update README if needed

5. Commit Your Changes¶

Write clear commit messages:

# Good
git commit -m "Add expiration date validation for links"

# Better (multi-line)
git commit -m "Add expiration date validation for links

- Validate ISO format for expiration dates
- Show error message for invalid formats
- Add tests for edge cases
- Update documentation

Fixes #123"

Commit message guidelines:

Start with a verb (Add, Fix, Update, Remove)
Keep first line under 50 characters
Add detailed description if needed
Reference issues with "Fixes #123"

6. Push and Create Pull Request¶

# Push to your fork
git push origin feature/your-feature-name

On GitHub:

Click "New Pull Request"
Select your branch
Fill out the PR template
Request reviews if you know relevant reviewers

Pull Request checklist:

Reviewing Pull Requests¶

Help review other contributions:

Test the changes locally
Review code for:
- Correctness
- Style consistency
- Test coverage
- Documentation
Provide feedback:
- Be constructive
- Suggest specific improvements
- Acknowledge good work

Development Guidelines¶

Project Structure¶

Understand the codebase:

trunk8/
├── app/                 # Main application
│   ├── auth/           # Authentication
│   ├── links/          # Link management
│   ├── main/           # Main routes
│   ├── utils/          # Utilities
│   ├── static/         # CSS, JS, images
│   └── templates/      # HTML templates
├── config/              # Configuration files
├── tests/              # Test files
├── docs/               # Documentation
└── run.py             # Entry point

Adding New Features¶

Discuss first - Open an issue or discussion
Design - Plan the implementation
Implement - Follow coding standards
Test - Add comprehensive tests
Document - Update all relevant docs

Dependencies¶

When adding dependencies:

Justify the need - Avoid unnecessary dependencies
Check licenses - Ensure compatibility

Update pyproject.toml:

dependencies = [
    "new-package>=1.0.0",
]

Run uv sync --extra dev to update lock file
Document usage and purpose

Database Migration (Future)¶

If implementing database support:

Use SQLAlchemy with Alembic
Keep migrations compatible with existing data
Provide migration documentation
Test with production data volumes

Testing¶

Running Tests¶

# Run all tests
pytest

# Run specific test file
pytest tests/test_links.py

# Run with coverage
pytest --cov=app --cov-report=html

# Run with verbose output
pytest -v

Writing Tests¶

Test categories: - Unit tests - Test individual functions - Integration tests - Test component interactions - End-to-end tests - Test complete workflows

Example test structure:

import pytest
from app.links.models import Link

class TestLink:
    """Test Link model functionality."""

    def test_link_creation(self):
        """Test basic link creation."""
        # Arrange
        link_data = {'type': 'redirect', 'url': 'http://example.com'}

        # Act
        link = Link('test', link_data)

        # Assert
        assert link.short_code == 'test'
        assert link.type == 'redirect'

    def test_expired_link(self):
        """Test link expiration detection."""
        # Test implementation

Test Coverage¶

Aim for:

80%+ overall coverage
100% coverage for critical paths
Test edge cases and error conditions

Documentation¶

Types of Documentation¶

Code Documentation
- Docstrings for all public functions
- Type hints for clarity
- Inline comments for complex logic
User Documentation
- Clear examples
- Common use cases
- Troubleshooting guides
API Documentation
- Endpoint descriptions
- Request/response examples
- Error codes

Building Documentation¶

# Serve documentation locally
mkdocs serve

# Build documentation
mkdocs build

Release Process¶

Version Numbering¶

We follow Semantic Versioning (MAJOR.MINOR.PATCH):

MAJOR - Breaking changes
MINOR - New features (compatible with existing installations)
PATCH - Bug fixes

Release Steps¶

Update version in pyproject.toml
Update CHANGELOG
Create release PR
Tag release after merge
Build and publish Docker image

Getting Help¶

Resources¶

Communication¶

Issues - Bug reports and feature requests
Discussions - Questions and ideas
Pull Requests - Code contributions

Recognition¶

Contributors are recognized in:

GitHub contributors page
Release notes
Documentation credits

Thank you for contributing to Trunk8! 🎉