Development workflow

The day-to-day cycle for adding or changing code in Starship.

Setup

git clone https://github.com/starship/starship.git
cd starship
cargo build --release

You'll typically work with cargo build (debug) for quick iterations and cargo build --release to compare against shipping behavior. Release builds turn on LTO and a single codegen unit (see [profile.release] in Cargo.toml), so they take much longer to compile.

Branching

git checkout -b feat/add-foo-module

Use a descriptive branch name. The repo follows the convention that branch prefixes match commit-message types: feat/, fix/, docs/, chore/, ci/, refactor/.

Commit messages

The repo uses Conventional Commits. release-please reads them when cutting a release, so they directly affect the changelog:

Prefix	Meaning
feat:	New feature (bumps minor)
fix:	Bug fix (bumps patch)
docs:	Documentation only
refactor:	No behavior change
perf:	Performance improvement
test:	Test-only changes
chore:	Tooling, deps, anything else
ci:	CI config
feat!: / fix!:	Breaking changes (bumps major after 1.x)

The release-please-config.json file in the repo root configures the bot.

Iterate

# Quick check
cargo check --workspace --all-features --locked

# Run a single module's tests
cargo test --all-features module_name::tests

# Run a single test by name
cargo test --all-features test_my_specific_thing

# Try the binary with a fake repo
mkdir /tmp/test && cd /tmp/test && touch foo.rs Cargo.toml && \
    /path/to/starship/target/debug/starship prompt

Iterate inside a real shell

# Replace your shipping starship for the current shell session only
hash -r
PATH="/path/to/starship/target/release:$PATH"
exec $SHELL

Then STARSHIP_LOG=debug and observe the session log file (~/.cache/starship/session_<id>.log) to see what's happening.

Pre-commit checklist

cargo fmt --all
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features --locked --workspace -- --include-ignored
dprint fmt

# If config struct fields changed:
cargo run --features config-schema -- config-schema > .github/config-schema.json

Open the PR

git push -u origin feat/add-foo-module

Then open a PR via the GitHub UI. The PR template asks you to confirm:

• Tests are passing locally.
• Documentation has been updated where applicable.
• The change is described in the PR body (especially anything user-visible).

CI matrix

.github/workflows/workflow.yml runs:

• rustfmt check
• clippy on Ubuntu, macOS, Windows
• cargo check on all-features, no-features, default-features
• Schema freshness check
• cargo llvm-cov test runs on Ubuntu/macOS/Windows × stable/nightly
• Windows MSI build via cargo-wix
• Code signing via SignPath (only on push to the canonical repo)
• Codecov upload

Other workflows:

• format-workflow.yml — fixes formatting on demand via a comment.
• release.yml — release-please-driven release process.
• publish-docs.yml — VitePress docs deploy.
• security-audit.yml — cargo-audit for known vulnerabilities.
• spell-check.yml — typos check (typos.toml).
• crowdin-pretranslate.yml — Crowdin sync.

After merge

PRs are squash-merged. Your branch is automatically eligible for release-please to roll into the next release on the next push to main.