Skip to main content

🔧 Contributing to Zi

Thank you for contributing to zi! This page covers the guidelines specific to the z-shell/zi repository. For the org-wide basics (branch model, commit format, PR checklist) see Getting Started.

Repository Overview​

Zi is a Zsh plugin manager written entirely in Zsh. The entry point is zi.zsh at the repository root, with sourced implementation in lib/zsh/. The installer lives in z-shell/src.

zi/
  zi.zsh            ← plugin manager entry point
  lib/zsh/          ← core plugin manager source
  docs/             ← repository-level docs (CONTRIBUTING.md, man page)
  tests/            ← focused Zsh regressions
  .github/
    workflows/      ← CI workflows and full stable qualification

Setting Up Locally​

git clone https://github.com/<your-username>/zi.git
cd zi
git remote add upstream https://github.com/z-shell/zi.git
git fetch upstream
git checkout -b feature-123 upstream/main

No build step is required — zi is pure Zsh. To test changes interactively, source the modified files in a Zsh session:

zsh
source zi.zsh

Running Tests​

Run native syntax checks and the focused Zsh regressions affected by your change:

zsh -f -n zi.zsh
zsh -f tests/ice-tokenizer.zsh
zsh -f tests/ci-registration.zsh

Read each test before running it and isolate inherited installation prefixes such as ZPFX. The contribution guide and Zsh workflow define the suite. Full stable qualification also runs the ZD integration suite, clean startup, and real-object lifecycle checks. Add or update focused tests when your change affects behavior.

Zi-Specific Commit Scopes​

In addition to the standard commit types, prefer these scopes when relevant:

ScopeCovers
corezi.zsh and its lib/zsh/ implementation
installinstaller scripts in src
ciGitHub Actions workflows
docsrepository-level documentation
annexannex API surface changes

Examples:

fix(core): resolve fpath duplication on plugin reload
feat(annex): expose atdelete hook to external annexes
docs(ci): document workflow trigger conditions

What Not to Add to Zi​

Off-limits
  • AGENTS.md, CLAUDE.md, GEMINI.md, .cursorrules, or any AI-specific config files
  • Secrets, credentials, or tokens of any kind
  • Files unrelated to the plugin manager itself

Opening Issues​

Before starting significant work, open an issue to discuss the change. Use the appropriate issue template:

TemplateWhen to use
Bug reportReproducible misbehavior
Feature requestNew capability
Annex proposalProposing a new annex

Protected main contributions​

Branch from current main and open your pull request into protected main:

  1. Keep feature, fix, and hotfix branches short-lived and linked to an issue.
  2. Every merge must pass full stable qualification and the required review.
  3. Ordinary pull requests use squash merge. Historical promotion ancestry remains preserved in main.

main remains the directly consumable stable ref. Signed version milestones are separate maintainer actions on the qualified current main commit; merging a pull request does not create a release. See ADR 0039 and the contribution guide for the current contract.

See Also​