Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
130 lines (94 loc) · 4.04 KB

CONTRIBUTING.md

File metadata and controls

130 lines (94 loc) · 4.04 KB
Raw

Contributing to gitquill

First off — thank you for taking the time to contribute! 🎉 gitquill is a community project and every contribution, however small, is welcome.

This document explains how to get set up and how to send a change.

🌱 Code of Conduct

By participating you agree to uphold our Code of Conduct. Be kind, be patient, be inclusive.

🛠️ Development setup

gitquill targets Node.js >= 18 and is written in TypeScript (ESM).

git clone https://github.com/Cryptoteep/gitquill.git
cd gitquill
bun install          # or: npm install
bun run build        # produces ./dist

You can now run the local binary:

./dist/index.js --version
./dist/index.js doctor

For an instant feedback loop during development:

bun run dev          # tsup --watch

Useful scripts

Script What it does
bun run build Type-check + bundle to dist/.
bun run typecheck tsc --noEmit only.
bun run lint ESLint.
bun run dev Watch mode rebuild.

🧪 Testing your changes

There's no formal test suite yet (see roadmap). Before opening a PR please:

  1. Run bun run typecheck and bun run lint — both must pass.
  2. Run ./dist/index.js doctor in a real git repository.
  3. Try both flows against a local Ollama model:
    • ./dist/index.js commit --dry-run
    • ./dist/index.js release --dry-run
  4. If you touch provider logic, sanity-check with at least one cloud preset (openai or groq).

📐 Commit conventions

gitquill dogfoods Conventional Commits. Every commit should look like:

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

<optional body>

Valid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert. Add ! for breaking changes, e.g. feat(provider)!: switch default to llama3.1.

(Yes, you can use gitquill itself to draft the message — we do!)

🔄 Pull request flow

  1. Open an issue first for non-trivial changes so we can align on scope.
  2. Fork the repo and create a branch named feat/…, fix/…, or docs/….
  3. Keep PRs focused — one logical change per PR.
  4. Update the README and docs if your change affects user-facing behaviour.
  5. Make sure CI is green.
  6. Write a clear PR description: what, why, how to test.

🧭 Architecture in 60 seconds

src/
  index.ts              CLI entry (commander)
  commands/
    commit.ts           gitquill commit
    release.ts          gitquill release
    config.ts           gitquill config …
    doctor.ts           gitquill doctor
  lib/
    ai.ts               OpenAI-compatible client (works with Ollama etc.)
    git.ts              git operations (simple-git wrapper)
    config.ts           ~/.gitquill/config.json load/save
    conventional.ts     Conventional Commits parse + format
    prompts.ts          All prompt templates live here
    logger.ts           Colored, TTY-aware logging
    interactive.ts      confirm / edit-in-$EDITOR helpers
  types.ts              Shared types & default config

The golden rule: everything goes through lib/. Commands orchestrate, libraries do the work. This keeps the surface area testable and swappable.

🐛 Reporting bugs

Open an issue with:

  • gitquill version (gitquill --version)
  • Node version, OS
  • The exact command you ran
  • The output of gitquill doctor
  • The relevant snippet of ~/.gitquill/config.json (redact your API key!)

✨ Suggesting features

We love well-scoped proposals. Open an issue with use case first, solution second — tell us what you're trying to accomplish before proposing an API.

🏷️ Release process (for maintainers)

Releases follow SemVer and are tagged vMAJOR.MINOR.PATCH. The CHANGELOG is generated with gitquill release --version vX.Y.Z (eat your own dog food).

Thanks again for helping make gitquill better. 💛