Contributing to Edgartools

July 27, 2026 · View on GitHub

A big welcome and thank you for considering contributing to Edgartools! We appreciate your interest in helping make this library better. 🎉

There are many ways to contribute, from reporting bugs and suggesting features to writing code, improving documentation, and sharing your expertise.

Ways to Contribute

  • Report Bugs: If you encounter a bug, please check if it has already been reported in the GitHub Issues. If not, please open a new issue. Include a clear title, a detailed description of the bug, steps to reproduce it, expected behavior, actual behavior, and your environment details (OS, Python version, Edgartools version).
  • Suggest Enhancements: Have an idea for a new feature or an improvement to an existing one? Open an issue using the "Feature request" template. Describe your idea clearly, why it would be beneficial, and any potential implementation details you've considered.
  • Improve Documentation: See a typo, something unclear, or an area that needs more explanation in the documentation or docstrings? Submit a pull request with your improvements!
  • Write Code: If you want to fix a bug or implement a new feature:
    1. Find an issue you want to work on (or open one).
    2. Discuss your plan in the issue comments if it's a significant change.
    3. Follow the development setup and contribution workflow below.
  • Share Expertise: If you have experience with SEC filings, XBRL, financial data analysis, or related areas, your insights are valuable! Participate in discussions on issues or share your knowledge.

Development Setup

This project uses Hatch for environment and project management.

  1. Fork & Clone: Fork the repository on GitHub and clone your fork locally: 
    git clone https://github.com/<YOUR_USERNAME>/edgartools.git
cd edgartools
  2. Install Hatch: If you don't have Hatch installed, follow the official installation guide.
  3. Activate Environment: Set up the development environment and install dependencies (including development tools like ruff, pytest, mkdocs): 
    hatch shell
    This command activates a virtual environment managed by Hatch with all necessary dependencies installed.

Contribution Workflow

  1. Create a Branch: Create a new branch for your changes, based on the main branch: 
    git checkout main
git pull origin main # Ensure you have the latest changes
git checkout -b your-feature-or-fix-branch-name
    Use a descriptive branch name (e.g., fix-filing-parsing-error, add-insider-transaction-api).
  2. Make Changes: Write your code or documentation improvements.
  3. Format & Lint: Ensure your code adheres to the project's style guidelines by running the formatter and linter: 
    # Format code
hatch run ruff format .
# Check for linting errors
hatch run lint
    Fix any reported issues.
  4. Test: Run the test suite to ensure your changes haven't introduced regressions: 
    hatch run cov
    Make sure all tests pass and coverage doesn't significantly decrease. Consider adding new tests for your changes if applicable.
  5. Commit: Commit your changes with a clear and descriptive commit message. Follow conventional commit message formats if possible (e.g., fix: Resolve issue with date parsing in Form 4, feat: Add support for 8-K item retrieval). 
    git add .
git commit -m "feat: Describe your change here"
  6. Push: Push your branch to your fork: 
    git push origin your-feature-or-fix-branch-name
  7. Open Pull Request: Go to the original edgartools repository on GitHub and open a pull request from your branch to the main branch.
    • Provide a clear title and description for your PR.
    • Reference any relevant issues (e.g., "Closes #123").
    • Explain the changes you made and why.
  8. Review: A maintainer will review your PR. Be prepared to discuss your changes and make further adjustments based on feedback.

Test Cassettes (VCR)

Network-dependent tests replay recorded SEC responses from tests/cassettes/ rather than hitting the network on every run. A cassette is the test's ground truth: when a test asserts that a section is 91,682 characters, the authority for that number is the recorded response body, not SEC. Cassettes are therefore held to the same standard as the assertions they support.

Record from live SEC, and don't edit afterwards. Delete the cassette and re-run the test to record it (record_mode is once, so an existing file is never overwritten). Never hand-edit a recorded response — not to shrink a large cassette, not to remove a field that makes a test flaky, and not to adjust a value so an assertion passes. An edited cassette produces a test that looks like it verifies against a real filing while verifying against something SEC never sent.

Record against main, not against your fix. If you record while your change is applied, the cassette captures your patched behaviour and the test can no longer fail if the fix regresses. Record first, then develop against the recording.

Keep cassettes small by scoping the test, not by trimming the file. If a cassette is unreasonably large, narrow what the test fetches — a smaller filing, a single request — and re-record.

CI will not generate cassettes for you. They are committed artifacts, and they are reviewed as part of the PR. Say in the PR description which filings you recorded and when, so a reviewer can spot-check a value against SEC directly.

Cassettes are loaded as plain data — recorded requests, headers and response bodies only. hatch run check-cassettes verifies this and runs in CI ahead of the test jobs; run it locally if you are about to run a branch you did not write.

Documentation Structure

EdgarTools uses a three-tier documentation system:

External Documentation (docs/)

  • Purpose: User-facing documentation published to edgartools.readthedocs.com
  • Content: API reference, user guides, tutorials, installation, configuration
  • Standards: Must be maintained, versioned, and follow consistent style
  • Audience: End users and developers using EdgarTools

Internal Documentation (docs-internal/)

  • Purpose: Internal planning, research, and development documentation
  • Content: Architecture decisions, feature proposals, research analysis, runbooks
  • Standards: Can include sensitive details, work-in-progress, more informal
  • Audience: EdgarTools maintainers and contributors

AI Documentation (ai_docs/)

  • Purpose: Documentation for AI agents working with the codebase
  • Content: Agent instructions, API context, code patterns, generated docs
  • Standards: CLAUDE.md is source of truth, context should be accurate and concise
  • Audience: AI assistants and automated tools

Local Documentation Management

To avoid conflicts over temporary documentation, use local exclusions instead of global .gitignore:

# Setup local exclusions (run once per developer)
cat >> .git/info/exclude << 'EOF'
# AI-generated documentation
ai_docs/generated/

# Module-specific ephemeral docs
edgar/**/.docs/

# Personal temporary docs
**/TEMP_*.md
**/WIP_*.md
**/LOCAL_*.md
EOF

Building Documentation Locally

To preview the external documentation site locally:

hatch run mkdocs serve

Then open your browser to http://127.0.0.1:8000.

Thank you again for your contribution!