🚀 Getting Started

This guide applies to all repositories in the Z-Shell organization. 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

All repositories follow the same two-branch model:

main  ←─── production (tagged releases only)
  ↑
next  ←─── integration branch  ← open all PRs here
  ↑
  ├── feat/<name>      new features
  ├── fix/<name>       bug fixes
  ├── perf/<name>      performance improvements
  ├── refactor/<name>  code refactors
  ├── docs/<name>      documentation updates
  └── ci/<name>        CI / workflow changes

Rules:

1. Always branch from next: git checkout -b fix/my-issue next
2. Open PRs targeting next — never target main directly
3. next → main happens via a release PR once next is stable
4. Hotfixes are the only exception — branch from main and open a PR against main

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
• Do not add Co-authored-by trailers — this is enforced by CI

To tidy commits before opening a PR:

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

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 next (or main for a hotfix)
• PR targets next
• 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/next  # for feature branches

Discussion First

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