Contributing to folder2md4llms

February 2, 2026 · View on GitHub

Thank you for your interest in contributing to folder2md4llms! This document provides guidelines for contributing to the project.

Code of Conduct

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

How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check existing issues to avoid duplicates. When creating a bug report, include:

  • Clear title and description
  • Steps to reproduce the problem
  • Expected behavior vs actual behavior
  • Environment details (OS, Python version, installation method)
  • Error messages or logs if applicable

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, include:

  • Clear title and description of the feature
  • Use cases - why this would be useful
  • Possible implementation - if you have ideas
  • Examples - mockups, code samples, etc.

Pull Requests

  1. Fork the repository and create your branch from main
  2. Make your changes following our coding standards (see below)
  3. Add tests if you're adding functionality
  4. Update documentation if needed
  5. Ensure tests pass - run pytest tests/
  6. Format your code - run ruff format .
  7. Lint your code - run ruff check .
  8. Write a clear commit message following Conventional Commits
  9. Submit the pull request

Updating the Homebrew Formula

When releasing a new version, the Homebrew formula must be updated in the homebrew-formulas repository.

cd ../homebrew-formulas
just release folder2md4llms  # Full workflow: update → test → commit → push

This automatically:

  • Fetches the latest version from PyPI
  • Downloads and calculates SHA256 checksum
  • Updates the formula file
  • Tests the installation
  • Commits with standardized message
  • Pushes to remote

Manual Workflow (Alternative)

If just is not available, you can update the formula manually:

1. Get Package Information from PyPI

VERSION=X.Y.Z  # Replace with new version
curl "https://pypi.org/pypi/folder2md4llms/$VERSION/json" | \
  jq -r '.urls[] | select(.packagetype=="sdist") | "URL: \(.url)\nSHA256: \(.digests.sha256)"'

2. Update the Formula

Navigate to the homebrew-formulas repository and edit the formula:

cd ../homebrew-formulas  # Use relative path from folder2md4llms directory

Edit Formula/folder2md4llms.rb:

  • Update the url line with the new URL
  • Update the sha256 line with the new hash

3. Test Locally

brew uninstall folder2md4llms 2>/dev/null || true
brew install --build-from-source ./Formula/folder2md4llms.rb
brew test folder2md4llms
folder2md --version  # Verify correct version

4. Audit the Formula

brew audit --strict --online folder2md4llms

5. Commit and Push

git add Formula/folder2md4llms.rb
git commit -m "folder2md4llms: update to version $VERSION"
git push

6. Verify Installation

brew uninstall folder2md4llms
brew install henriqueslab/formulas/folder2md4llms
folder2md --version

Note: The automated workflow using just is preferred for consistency and efficiency. See the homebrew-formulas repository for additional utility commands like just list, just check-updates, and just sha256

Development Setup

Prerequisites

  • Python 3.11 or higher
  • uv (recommended) or pip
  • libmagic (for file type detection)

Installation

# Clone your fork
git clone https://github.com/YOUR-USERNAME/folder2md4llms.git
cd folder2md4llms

# Install dependencies with uv
uv sync --all-extras

# Or with pip
pip install -e ".[dev]"

Running Tests

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=src/folder2md4llms --cov-report=html

# Run specific test file
pytest tests/test_cli.py

Code Quality

We use several tools to maintain code quality:

# Format code
ruff format .

# Lint code
ruff check .

# Type checking
mypy src/folder2md4llms/

Justfile Commands

We provide a justfile for common development tasks. If you have just installed, you can use these commands:

# Run all tests with coverage
just test

# Format and lint code (auto-fix issues)
just fix

# Check code quality without making changes
just check

# Build distribution packages
just build

These commands combine multiple tools and provide a convenient development workflow.

Coding Standards

Python Style

  • Follow PEP 8 style guide
  • Use type hints for function parameters and return values
  • Write docstrings for public functions and classes (Google style)
  • Keep lines under 88 characters (Ruff/Black default)
  • Use meaningful variable and function names

Git Commit Messages

Use Conventional Commits format:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring
  • test: Adding or updating tests
  • chore: Maintenance tasks

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing to folder2md4llms! 🎉