Skip to content

Contributing to FenLiu

Thank you for your interest in contributing! This guide explains how to contribute code, documentation, or ideas.

Code of Conduct

Be respectful and constructive. We welcome all contributions regardless of experience level.

Getting Started

1. Fork & Clone

git clone https://codeberg.org/marvinsmastodontools/fenliu.git
cd fenliu

2. Create a Feature Branch

git checkout -b feature/my-feature
# or
git checkout -b fix/my-bug-fix

Use descriptive branch names: feature/image-gallery, fix/database-session-leak

3. Set Up Development Environment

uv sync -U --all-groups

4. Make Changes

Follow the code style and structure of the project.

Submitting Changes

Code Quality

Run tests before submitting:

pytest

Run linting:

ruff check .

Format code:

ruff format .

Commit Messages

Use clear, descriptive messages:

feat: add image gallery navigation to queue preview

- Add next/previous buttons for multi-image posts
- Add keyboard navigation (arrow keys)
- Add image counter display
- Fixes #123

Format: <type>: <description>

Types: - feat - New feature - fix - Bug fix - docs - Documentation - style - Formatting - refactor - Code restructuring - test - Tests - chore - Maintenance

Pull Request

  1. Push your branch: git push origin feature/my-feature
  2. Create a pull request on GitHub
  3. Provide a clear description:
  4. What problem does this solve?
  5. How does it work?
  6. Any breaking changes?
  7. Link related issues: Fixes #123

Maintainers will review and provide feedback.

Documentation Contributions

Building Docs

mkdocs serve

Visit http://localhost:8000 to preview changes.

Adding Pages

  1. Create .md file in appropriate directory
  2. Update mkdocs.yml nav section
  3. Build and test locally
  4. Submit pull request

Documentation Standards

  • Use clear, simple language
  • Include examples
  • Link to related pages
  • Update version info if relevant

Testing

Running Tests

pytest                    # Run all tests
pytest tests/test_api.py  # Run specific file
pytest -k test_name       # Run specific test
pytest -v                 # Verbose output
pytest --cov             # With coverage

Writing Tests

Tests go in tests/ directory. Structure:

def test_feature_description(client: TestClient) -> None:
    """Test specific behavior of feature."""
    response = client.get('/endpoint')
    assert response.status_code == 200
    assert response.json()['field'] == 'value'

Development Tips

Database Changes

Use Alembic for schema migrations:

alembic revision --autogenerate -m "add new_field to users"
alembic upgrade head

Running the App

python -m uvicorn fenliu.main:app --reload

Debugging

Add logging:

import logging
logger = logging.getLogger(__name__)
logger.debug("Debug message")

Or use Python debugger:

import pdb; pdb.set_trace()

Common Tasks

Adding a New API Endpoint

  1. Create handler function in src/fenliu/api/
  2. Add route to fenliu/src/fenliu/api/__init__.py
  3. Add tests in tests/
  4. Document in docs/api/

Adding a UI Page

  1. Create handler in src/fenliu/main.py
  2. Create template in src/fenliu/templates/
  3. Add navigation link in partials/header.html
  4. Document in docs/user-guide/

Adding a Model

  1. Add class to src/fenliu/models.py
  2. Create Alembic migration
  3. Add tests
  4. Document in docs/architecture/models.md

Performance Considerations

  • Use SQLAlchemy eager loading to prevent N+1 queries
  • Cache expensive operations
  • Profile before optimizing
  • Consider database indexes for frequently-queried fields

Code Organization

src/fenliu/
├── api/              # API endpoints
├── models.py         # Database models
├── main.py           # Web app & routes
├── config.py         # Configuration
├── database.py       # Database connection
├── liveviews.py      # PyView components
├── services/         # Business logic
├── schemas.py        # Pydantic schemas
├── templates/        # Jinja2 templates
├── static/           # CSS, JS, images
└── utils/            # Utilities

Release Process

Maintainers handle releases:

  1. Update version in src/fenliu/__init__.py
  2. Update CHANGELOG
  3. Create git tag
  4. Deploy versioned docs with Mike

Questions?

  • Ask in GitHub Discussions
  • Comment on related issues
  • Reach out to maintainers

Thanks for contributing!