Ship

What Is This?

Overview

Ship is a structured development workflow tool that automates the most repetitive and error-prone steps involved in preparing and delivering code changes. It handles branch detection, base branch merging, test execution, diff review, version bumping, changelog updates, commit creation, push operations, and pull request creation in a single coordinated sequence. Rather than manually executing each of these steps in order, developers can trigger the entire pipeline with a simple command.

The tool is designed to reduce cognitive overhead during the final stages of a development cycle. When code is ready to ship, the last thing a developer wants is to forget a step, such as bumping the version number or updating the changelog, and have to go back and fix it after the fact. Ship enforces a consistent, repeatable process every time code is pushed toward the main branch.

Ship integrates naturally into conversational development environments and AI-assisted coding workflows. It activates when phrases like "ship this", "deploy", "push to main", or "create a PR" are used, and it can proactively suggest itself when a developer indicates that code is ready for review or release.

Who Should Use This

• Solo developers who want a consistent release process without maintaining complex CI scripts
• Team leads who need to enforce a standard workflow across contributors
• AI-assisted developers working in environments where natural language triggers automate tooling
• Backend engineers managing versioned APIs or services that require changelog discipline
• Open source maintainers who regularly create pull requests and need to keep release history clean
• DevOps engineers looking to standardize the handoff between development and deployment pipelines

Why Use It?

Problems It Solves

• Developers frequently forget to bump version numbers before pushing, causing inconsistent release tags and confusing changelogs
• Manual merging of the base branch before pushing leads to avoidable conflicts and failed CI runs
• Skipping test execution before creating a pull request wastes reviewer time and delays merges
• Inconsistent commit message formats and missing changelog entries make release history difficult to audit
• Context switching between multiple terminal commands during the ship process introduces mistakes and slows delivery

Core Highlights

• Automatically detects and merges the current base branch before committing
• Runs the full test suite and halts the workflow if tests fail
• Reviews the diff before finalizing the commit, giving developers a last checkpoint
• Bumps the VERSION file according to semantic versioning conventions
• Updates the CHANGELOG with a structured entry for the current release
• Creates a commit with a consistent, descriptive message
• Pushes the branch to the remote repository
• Opens a pull request against the base branch automatically

How to Use It?

Basic Usage

Trigger the Ship workflow by invoking it directly or through a natural language instruction in a supported environment:

## Direct invocation
ship

## Or through a conversational AI interface
"Ship this feature"
"Push to main and create a PR"
"Deploy the current branch"

The workflow will execute each step in sequence, pausing for confirmation where appropriate.

Specific Scenarios

Scenario 1: Feature branch ready for review A developer finishes a feature and wants to open a pull request. Ship merges the latest main branch, runs tests, bumps the minor version, updates the changelog, and creates the PR automatically.

Scenario 2: Hotfix deployment A critical bug fix is ready. Ship detects the base branch, runs tests to confirm the fix does not introduce regressions, bumps the patch version, and pushes the branch for immediate review.

Real-World Examples

## After completing a feature
git checkout feature/user-auth
ship
## Ship merges main, runs pytest, bumps 1.2.3 -> 1.3.0, updates CHANGELOG, commits, pushes, opens PR

## Patch release after a bug fix
ship
## Bumps 1.3.0 -> 1.3.1, documents fix in CHANGELOG, creates PR

When to Use It?

Use Cases

• Releasing a completed feature branch to the main development line
• Publishing a patch release after a targeted bug fix
• Preparing a release candidate for staging or production deployment
• Submitting open source contributions as structured pull requests
• Enforcing version discipline on projects with multiple active contributors
• Automating the final steps of a sprint delivery cycle
• Reducing manual steps in AI-assisted pair programming sessions

Important Notes

Requirements

• A VERSION file must exist at the project root and follow semantic versioning format
• A CHANGELOG file must be present and formatted for automated entry insertion
• The repository must have a configured remote with push access
• A test command must be defined and executable from the project root