Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
128 lines (86 loc) · 4.2 KB

CONTRIBUTING.md

File metadata and controls

128 lines (86 loc) · 4.2 KB

Contributing to forgit

Thanks for your interest in contributing to forgit.

This document covers the repository-specific workflow for reporting issues and opening pull requests. For installation, usage, commands, and configuration, see README.md.

Before You Start

Before opening an issue or pull request, please make sure that you:

  • read through README.md
  • use the latest released version of forgit
  • search existing issues and pull requests for duplicates

Repository Map

These are the main places you will usually need to touch:

Making Changes

When changing or adding behavior, prefer to follow existing command patterns already used in the repository.

If you add a new command or rename an existing one, update all affected layers together:

Please keep changes focused. Small pull requests are easier to review and usually get merged faster.

When possible, keep core logic testable by sourcing bin/git-forgit directly and calling helper functions from unit tests.

Development Dependencies

To run the same checks as CI, make sure these tools are available locally:

  • bash, zsh, and fish
  • shellcheck
  • curl
  • bashunit as lib/bashunit

If lib/bashunit is not available yet, install it once with:

curl -s https://bashunit.typeddevs.com/install.sh | bash -s 0.31.0

Local Validation

Before opening a pull request, run the checks that match the current CI workflow:

shellcheck forgit.plugin.sh bin/git-forgit
lib/bashunit .
bash forgit.plugin.sh
zsh forgit.plugin.zsh
fish conf.d/forgit.plugin.fish

In your pull request, report which shells and operating systems you tested.

Commit Messages

This repository uses Conventional Commits, and pull requests are checked accordingly in CI.

Common examples include:

  • feat: new features
  • fix: bug fixes
  • docs: documentation changes
  • style: formatting-only changes
  • refactor: code changes that neither fix a bug nor add a feature
  • test: test additions or updates
  • chore: maintenance work
  • perf: performance improvements
  • ci: CI or automation changes

Scopes can optionally clarify which part of the project changed (e.g., fix(diff)); keep them short and relevant.

Use commit messages to explain:

  • what changed
  • why the change is needed

Do not focus the commit message on implementation mechanics unless that detail is important to understand the change.

Good examples:

fix: keep worktree add rooted at the main worktree

Adding from a linked worktree created nested .wt directories in the current
worktree. Keep new worktrees rooted at the main worktree so the default target
location stays consistent.

docs: add contributor workflow guide

Document the repository-specific review, testing, and completion update
expectations so new contributors do not have to infer them from old issues.

Pull Requests

Before submitting a pull request, make sure that you:

  • perform a self-review
  • add comments where the code is hard to understand
  • add or update unit tests when behavior changes
  • update documentation when the change is user-visible
  • summarize the pull request in terms of what changed and why

Please use the pull request description to give reviewers the context they need. A short explanation of the approach is useful, but the main focus should be the behavior change and its motivation.

Maintainers