Contributing & Development

Help make GitLegends even better.

GitLegends is an open-source project (MIT licensed) and welcomes contributions from the community. Whether you want to fix a bug, add a new feature, improve documentation, or tailor the tool to your needs, this guide will help you get started with developing and extending GitLegends.

Project Source & Structure

The source code is organized as a Python package named legends. Key components include:

  • CLI Interface: legends/cli.py – This defines the command-line argument parsing and maps subcommands to their handlers.
  • Commands: legends/commands/ – A module containing implementations for each subcommand (create_repo.py, create_branch.py, commit.py, etc.). Each command module has an add_parser function (to integrate with argparse) and a handle function containing the logic.
  • Core Utilities: legends/core/ – Functions that wrap Git and GitHub CLI calls (git_ops.py, gh_cli.py, etc.), and other core logic like merging (merge_ops.py).
  • Templates: legends/templates/ – Contains text files used for default commit messages, PR titles, bodies, and merge commit messages. These are loaded and formatted by the code in templates/__init__.py.
  • Configuration: legends/config.py – Handles loading config from YAML and environment, and defines the AppConfig dataclass.
  • Exceptions: legends/exceptions.py – Custom exception classes used in the project.
  • Utility functions: legends/utils.py – Additional helpers for running subprocess commands, date normalization, identity resolution, etc.

When extending functionality, you’ll likely be adding to the commands or core modules. For instance, if adding a new subcommand, you would create a file in commands/, implement logic possibly using core functions, and register it in commands/__init__.py.

Setting Up a Dev Environment

  1. Fork and Clone: Start by forking the GitLegends repository on GitHub and cloning your fork locally.
  2. Install for Development: As mentioned in the Installation section, run:
    python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
    This installs the package in editable mode and also installs dev dependencies (like testing and linting tools).
  3. Verify Setup: Run make verify-env if available, or manually check legends --help to ensure the CLI is working from your development environment.

Running Tests and Linting

If the project includes tests (it likely uses pytest given the dev dependencies), run:

pytest

to execute the test suite. Ensure all tests pass after your changes.

Code style is maintained with tools like ruff (for linting) and black (for formatting). You can run:

ruff .        # to lint
black .       # to format

Make sure your code follows the style guidelines. Often, you can run make lint or make format if provided.

Adding Features or Fixes

  • New Features: Propose your idea by opening an issue or discussion, if one isn’t already open, to get feedback. Then implement it in a new branch. Adhere to the existing code style and patterns. For example, follow how other commands are implemented. If adding a new CLI flag, integrate it into the argparse configuration in cli.py or within the specific command parser.
  • Bug Fixes: Reproduce the issue, write a test if possible, then fix the logic. Keep the fix focused and include a clear description in your commit/PR.
  • Documentation: If you add or change functionality, update the relevant documentation (docs pages or README) to reflect it. Good documentation is as important as code.

Extending for Personal Use (SDK-Like Usage)

While GitLegends is primarily a CLI tool, you may use its core functions in your own scripts. For example, you could import legends.core.git_ops to call lower-level functions. Just note that the stability of such internal interfaces isn’t guaranteed the way the CLI is. If you find yourself heavily using internals, consider contributing higher-level features to the project.

If you want to customize things like commit message templates or add specialized behavior, currently that means modifying the source. Forking the project is an option for highly tailored use-cases. Keep an eye on the project’s repository – if there’s interest, the maintainers might abstract more “SDK” like features or extension hooks in the future.

Submit a Pull Request

When your changes are ready:

  1. Commit your changes with clear messages. If your changes relate to an issue, consider including references (e.g., “Fixes #123 – Add support for X”).
  2. Push your branch to your fork on GitHub.
  3. Open a Pull Request against the upstream repository’s main branch. Fill out the PR template if provided, explaining what your change does and why.
  4. Ensure CI checks (if any) pass. Be responsive to any review feedback from maintainers.

Community and Support

Check out the project’s GitHub page for any contribution guidelines specific to that project (like a CONTRIBUTING.md or code of conduct). It’s good to familiarize yourself with the preferred communication channels – some projects use GitHub Issues, Discussions, or a chat for collaboration.

You can also raise questions or ideas by opening an issue. Since GitLegends is a relatively niche tool, any feedback or suggestions you have are likely welcome.

Future Ideas (Get Involved!)

Some areas where contributions could be valuable:

  • Timeline Scripting: as mentioned in examples, perhaps adding a feature to read from a timeline spec file and execute multiple steps.
  • Template Customization: allowing users to provide their own templates for commit/PR messages via config.
  • Platform Support: ensuring compatibility with Windows environments (path handling, etc.), if not already working.
  • Error Handling & UX: making error messages friendlier and more actionable.
PreviousFAQ & Troubleshooting