🚀 Getting Started

This guide covers the conventions shared across the Z-Shell organization — commit format, pull request workflow, and review expectations. Where a convention differs per repository, such as the branch model below, the guide says so and links the authoritative source. Repo-specific additions (zi, wiki, etc.) are documented in their own sub-pages.

Prerequisites

• Git ≥ 2.30
• Zsh ≥ 5.8
• A GitHub account

Fork and Clone

# 1. Fork the repo on GitHub, then clone your fork
git clone https://github.com/<your-username>/<repo>.git
cd <repo>

# 2. Add the upstream remote
git remote add upstream https://github.com/z-shell/<repo>.git

Branch Model

The organization default is trunk-based development on main. Branch from the current main and open your pull request into main.

Zi uses protected main with full stable qualification before every merge. Its former next integration model is retired under ADR 0039. An old next reference does not change the contribution target.

Check the repository instructions

Opening a pull request against the wrong base is a common first-time contribution mistake. Read the owning repository's contribution guidance and AGENTS.md, and use main.

The authoritative per-repository table lives in ADR 0019: Trunk-on-Main Default. At the time of writing:

Integration branch	Repositories
trunk on main	all repositories, including zi

Consult the ADR rather than this table if the two ever disagree; the ADR is the source of truth, and changing a repository's model requires amending it.

Branch naming

Use the issue-linked organization names:

feature-<issue>  planned features, documentation, refactors, and maintenance
bug-<issue>      non-critical bug fixes
hotfix-<issue>   urgent fixes branched from the stable or deployment ref

Rules:

1. Branch from current main and open the pull request into main.
2. Keep the branch short-lived and linked to its owning issue.
3. For Zi, every merge must pass full stable qualification. Hotfixes use the same protected main path.

Commit Message Format

All commits must follow Conventional Commits:

type(scope): short description

Optional body — explain what and why, not how.
Wrap at 72 characters.

Optional footer(s):
Fixes #123
BREAKING CHANGE: description of what breaks

Allowed Types

Type	Purpose
feat	New feature
fix	Bug fix
perf	Performance improvement
refactor	Code restructure, no behavior change
docs	Documentation only
test	Test additions or corrections
ci	CI/CD pipeline changes
chore	Routine maintenance
revert	Revert a previous commit

Rules

• Subject line: imperative mood, ≤ 72 characters, no trailing period
• Breaking changes: use ! suffix (feat!:) and add a BREAKING CHANGE: footer
• Co-authored-by trailers must credit a real human — including yourself as the pull request author. Never credit a bot, AI agent, or automation as a co-author. z-shell/.github and z-shell/zi enforce this in CI; the other repositories rely on the author until their own check is live

To tidy commits before opening a PR:

git rebase -i $(git merge-base HEAD main)

What Not to Add

• AGENTS.md, CLAUDE.md, GEMINI.md, .cursorrules, or any AI-specific config files
• Secrets, credentials, or API tokens of any kind
• Binary files unrelated to the project

Pull Request Checklist

Before opening a PR:

• Branched from current main
• Pull request targets main
• Commits follow Conventional Commits
• No secrets or AI config files added
• Relevant docs or tests updated
• All CI checks pass

Keeping Your Fork Up to Date

git fetch upstream
git rebase upstream/main

Discussion First

Before starting significant work, open an issue to discuss the change. This avoids duplicated effort and ensures alignment with the project roadmap.