Contributing to Writer Framework

November 14, 2025 · View on GitHub

Thank you for your interest in contributing to Writer Framework.

Ways to contribute

Report bugs: Include steps to reproduce the bug. Use "Issues" on GitHub.
Suggest enhancements: Use "Discussions" on GitHub for feature requests.
Browse Issues and Discussions: See if you can help with existing issues.

Development Setup

Prerequisites

Python 3.9.2 - 3.12
Node.js 22.x
Poetry for Python dependency management

Setup Steps

Install dependencies:

poetry install --with build
alfred install.dev

Activate virtual environment:

# Bash/Zsh/Csh
eval "$(poetry env activate)"

# Fish
eval (poetry env activate)

# PowerShell
Invoke-Expression (poetry env activate)

Test the setup:
```
writer edit apps/hello --port 5000
```

Frontend Development

For frontend development with auto-reload:

Run the app on default port:
```
writer edit apps/hello
```
Start the frontend dev server:
```
npm run dev
```

This will start the frontend development server with auto-reload for faster development.

Development Workflow

Create a feature branch off dev:

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

Make your changes and ensure they pass all checks
Run tests locally:
```
alfred ci
```
Create a pull request to the dev branch

Testing and Code Quality

Running Tests

# Run all tests (backend + frontend)
alfred ci

# Backend only
alfred ci --back

# Frontend only  
alfred ci --front

# End-to-end tests
alfred ci --e2e chromium

Code Standards

Backend: Use ruff for linting (automatically runs in CI)
Frontend: Use Prettier for formatting
Type checking: mypy validation is required
Tests: All tests must pass

CI Requirements

Your pull request must pass all CI checks:

Python linting (ruff)
Type checking (mypy)
Backend tests (pytest)
Frontend linting and build
End-to-end tests (when applicable)

The CI runs on Python versions 3.9-3.13 and Node.js 22.x.