Contributing to F2 Commander

Development Setup

F2 Commander uses uv for development. Here's how to get started:

1. Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clone the repository

git clone https://github.com/candidtim/f2-commander.git
cd f2-commander

3. Run F2 Commander

# Run directly with uv (installs dependencies automatically)
uv run f2

4. Run tests

uv run pytest

5. Code quality checks

# Run all checks (ruff + mypy)
./check

# Or run individually:
uvx ruff check
uvx mypy

Development with hot reload

For development with Textual's dev tools:

# Terminal 1: Start Textual console
uv run textual console

# Terminal 2: Run F2 in dev mode
uv run textual run --dev f2.main:main

This gives you live console output, DOM inspection, and hot reloading.

Code Quality Standards

All code contributions must meet these standards:

✓ Must pass code quality checks

./check  # Runs ruff (linter) and mypy (type checker)

✓ Type hints required

All functions and methods must have type hints:

def copy_file(source: Path, dest: Path) -> None:
    """Copy a file from source to destination."""
    ...

✓ Tests for new features

Add tests for new functionality using pytest:

def test_copy_operation():
    """Test that files are copied correctly."""
    # Test implementation
    ...

✓ Follow existing patterns

• Error handling with decorators (see errors.py)
• Async operations with @work decorator
• Pydantic models for data validation
• Immutable Node objects for filesystem entries

✓ Documentation

• Add docstrings to public functions and classes
• Update relevant documentation files
• Include code comments for complex logic

Pull Request Process

1. Fork the repository

   Click the "Fork" button on the GitHub repository.

2. Create a feature branch

   git checkout -b feature/my-new-feature

3. Make your changes

   • Write clean, well-documented code
   • Follow existing code style
   • Add tests for new functionality

4. Test your changes

   # Run tests
   uv run pytest
   
   # Run code quality checks
   ./check
   
   # Test manually
   uv run f2

5. Commit your changes

   git add .
   git commit -m "Add feature: description of your changes"

6. Push to your fork

   git push origin feature/my-new-feature

7. Create a Pull Request

   Go to the original repository and click "New Pull Request". Provide:

   • Clear description of what the PR does
   • Reference any related issues
   • Screenshots or examples if applicable

8. Add license headers

   All new source files must include the MPL 2.0 license header:

   # This Source Code Form is subject to the terms of the Mozilla Public
   # License, v. 2.0. If a copy of the MPL was not distributed with this
   # file, You can obtain one at https://mozilla.org/MPL/2.0/.
   #
   # Copyright (c) 2024 Your Name

Project Structure

Understanding the codebase:

f2/
├── app.py              # Main application and orchestration
├── main.py             # Entry point and CLI
├── config.py           # Configuration management with Pydantic
├── commands.py         # Command data structures
├── errors.py           # Error handling decorators
├── shell.py            # External tool detection and integration
├── fs/
│   ├── node.py         # Immutable filesystem node abstraction
│   ├── util.py         # Low-level filesystem operations
│   └── arch.py         # Archive filesystem support
└── widgets/
    ├── filelist.py     # File browser widget (main UI)
    ├── preview.py      # File preview widget
    ├── panel.py        # Panel container
    ├── dialogs.py      # Dialog widgets
    ├── bookmarks.py    # Bookmark management
    ├── config.py       # Configuration dialog
    ├── connect.py      # Remote connection dialog
    └── help.py         # Help widget

If using a coding agent (Claude Code, etc.), point it to the documentation in the doc/ directory:

• PRD files - Product requirements (what features do)
• ARCH files - Architecture (how systems are designed)
• SOP files - Standard operating procedures (how to implement features)

License

All contributions to F2 Commander are accepted under the Mozilla Public License 2.0.

By submitting a pull request, you agree to license your contribution under MPL 2.0 and confirm that you have the right to do so.

Community Guidelines

• Be respectful - Treat everyone with respect and kindness
• Be constructive - Provide helpful feedback and suggestions
• Be patient - F2 Commander is maintained by volunteers
• Be inclusive - Welcome newcomers and help them get started

Project Links

• GitHub Repository: https://github.com/candidtim/f2-commander
• Issues: Report bugs and request features
• PyPI: https://pypi.org/project/f2-commander/