Skip to content

AGENTS.md

Latest commit

 

History

History
94 lines (74 loc) · 4.67 KB

AGENTS.md

File metadata and controls

94 lines (74 loc) · 4.67 KB
Raw

Contribution guidelines

Before starting work, read and follow CONTRIBUTING.md, including the Prevent agent impersonation section governing agent identification and separation of unaltered user statements when communicating through a person's account.

Prefer pull requests: a PR can serve as an issue with a fix attached. Do not create an issue solely to follow it immediately with a PR that fixes it; describe the problem in the PR instead.

Gix backend implementations

Gix backend operations must use Gix through the supported GixPython (gix) APIs. Python/stdlib implementations, direct filesystem inference, and custom native implementations outside Gix are not substitutes for a missing Gix operation. Do not implement Git behavior independently to avoid CLI calls.

"Native" in code, documentation, reports and benchmarks means execution by Gitoxide through GixPython's gix API. It never means Python-implemented Git behavior. Every eliminated CLI call must be backed by identified Gix calls.

Python glue may validate inputs, adapt Gix results to GitPython's return types and formatting, manage the retained gix.Repository, and select a CLI fallback. It must not invent a successful result or repair missing Git semantics with a separate implementation. Retaining and explicitly recreating a Gix repository through the shared accessor is allowed.

Adapting native locations may append the fixed metadata leaf names modules and COMMIT_EDITMSG to Repository.git_dir(), whose location Gix resolves. Input paths may be canonicalized before reopening through Gix; return metadata from that native handle. These adaptations must match Git in regression tests and do not authorize a Python implementation of the general --git-path rules.

If Gix lacks a capability, differs from the required behavior, or its use is unclear, keep the existing Git CLI path and document the gap in doc/gix-backend.md. State the expected behavior, available evidence, and what GixPython or Gitoxide needs to expose or fix upstream. Tests, coverage reports and benchmark ceilings must reflect that fallback; a lower CLI count alone does not demonstrate a Gix implementation.

Track every observed difference from the equivalent Git operation as a Git compatibility bug, even if the Gix behavior is intentional. Gix must provide matching behavior, at least through a mode as strict as Git. Record Git's expected behavior, Gix's actual behavior, versions, reproduction or regression, and the affected adapter/fallback in the ledger. Keep these bugs open when a Gix-based adapter workaround restores parity; close them only after verifying the upstream fix or compatible mode. Distinguish demonstrated mismatches from missing APIs and unverified behavior. Do not repair a compatibility bug by implementing Git semantics in Python.

Commit messages

Follow Conventional Commits for every commit. Every commit must have a descriptive title and a substantive body. Title-only commit messages are not acceptable.

Formatting

Write commit messages in Markdown and assume readers view them with syntax highlighting. Enclose code identifiers, package and module names, file paths, and shell commands in backticks. Use Markdown whenever it helps readers understand or navigate the prose.

Titles

  • Every title must use the form type: description or type(scope): description.
  • Use feat: for user-visible features and fix: for user-visible fixes.
  • Use appropriate prefixes for other changes, such as docs:, test:, ci:, build:, refactor:, perf:, style:, or chore:.
  • Breaking changes must use ! immediately before the colon, for example feat!:, refactor!:, or a scoped form such as fix(repo)!:.
  • Optionally scope a commit to the affected component, for example fix(repo):.

Example titles:

  • feat: add support for a new Git option
  • fix(repo): handle bare repositories correctly
  • build!: drop support for an older Python version
  • ci: add an independent documentation build
  • refactor(repo): simplify repository initialization

Body

The body must explain the problem or motivation, what changed, and why the chosen approach addresses it. Include relevant behavior before and after the change, design decisions, limitations, and validation results. Scale the detail to the change; do not add boilerplate or claim checks that were not run.

Commit messages must stand on their own. Put the information needed to understand and review the change in the commit body, even when it also appears in a pull request description. PR and issue links may provide additional context, but must not substitute for that explanation.