Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

shipjs

algolia62.7kMIT0.27.0

Take control of what is going to be your next release.

readme

🛳 Ship.js

npm CircleCI NPM All Contributors Chat on Slack

Take control of what is going to be your next release.
https://community.algolia.com/shipjs/

Features

  • Automated
    • Minimize your effort for release and make less mistakes.
  • Asynchronous
    • You don't have to release on your local machine. Do it asynchronously and continue your work.
  • Collaborative
    • Don't sweat it alone. Review the next release on pull request with your colleagues.

Installation

Running the following command will guide you to set it up interactively.

npx shipjs setup

This interactive CLI will help you install Ship.js into your package and create a tailored config file for your project.

npx shipjs setup

Why 🤷🏻‍

Coding is fun, debugging and testing are okay, but releasing is NOT.

When releasing, you go through something like the following:

  • Update the version in package.json
  • Update the changelog
  • Actually release it (e.g. npm run build && npm publish)
  • Create a git tag
  • Create a release on GitHub

What could go wrong?

  • You might make mistakes during the release.
    • Environments are different across your team members.
    • You're releasing alone because the whole process happens on your local machine.
    • It's not your everyday-job. Mistakes can happen.
  • You are blocked and cannot do anything else until it's done.
    • Even if you have a release script, you need to watch until the script finishes well.
    • You don't want to switch to another feature branch and work there until the script finishes.

How to solve them❓

In Ship.js, the release process consists of three parts.

Part 1. Preparation (shipjs prepare)

Preview

Run shipjs prepare and it will briefly do the following:

  • Figure out next version.
  • Update the version and changelog.
  • Create a pull request.

It takes less than a couple of minutes.

Part 2. Review

  • Review the PR by yourself, or with your colleagues.
  • Add more commits to the PR if you want.
  • You can hold the release, build from the staging branch and test it manually.
  • If you want to cancel the release, just close the PR and delete the staging branch.

When you think it's ready to release, merge the PR.

Part 3. Trigger a release (shipjs trigger)

Run shipjs trigger and it will briefly do the following:

  • Run a final test (unit, e2e, etc).
  • Release it to NPM (or elsewhere as you configure it).
  • Create a git tag for the version.
  • Create a release for the tag on GitHub.

You can manually run shipjs trigger on the base branch after the PR is merged.

However you can also configure your CI service(e.g. CircleCI) to do this for you. It means the longest process is on the CI service asynchronously, not occupying your working environment.

Getting Started

Let's move on to the guide.

Or, you can watch this video if you prefer.

Getting Started with Ship.js

How is it different from semantic-release?

semantic-release is a tool for fully automated version management and package publishing.

Ship.js gives you more control over the release process. Ship.js automatically creates a PR before publishing every release, so that you can:

  • Confirm the next version is correct.
  • Confirm which commits are going to be released and discuss them with colleagues.
  • Edit the automatically generated changelog for clarity & readability.
  • Run any automated tests on the package release candidate.
  • Build a release candidate automatically (with Pika CI or CodeSandbox).

How to Contribute?

Read Contribution Guide →

Contributors ✨

Thanks goes to these wonderful people (emoji key):


Eunjae Lee

💻 📖

Fred K. Schott

📖

Yasuaki Uechi

💻 📖

Dmitry Ivakhnenko

💻 📖

James George

💻 📖

kazuya kawaguchi

💻 📝

tyankatsu

💻 📖

Haroen Viaene

💻

Shinya Ohyanagi

💻

Donghoon Song

💻

Miyata Jumpei

💻

lulzneko

💻 📖

Vinayak Kulkarni

💻

This project follows the all-contributors specification. Contributions of any kind welcome!

Badge deploy

Show the world you're using Ship.js

[![deploy](https://img.shields.io/badge/deploy-🛳%20Ship.js-blue?style=flat)](https://github.com/algolia/shipjs)
<a title="deploy" href="https://github.com/algolia/shipjs" rel="nofollow">
  <img src="https://img.shields.io/badge/deploy-🛳%20Ship.js-blue?style=flat" />
</a>

changelog

0.27.0 (2024-12-10)

Features

BREAKING CHANGES

  • code is in in ES Modules now and earliest node support is 18

0.26.4 (2024-08-20)

Bug Fixes

0.26.3 (2023-04-12)

Bug Fixes

  • github: update parameters used during upload of release assets (#1000) (0e66d1a)

0.26.2 (2023-04-06)

Bug Fixes

0.26.1 (2023-03-21)

Bug Fixes

  • github-actions: update versions of checkout and node actions (#996) (c4ad293)

0.26.0 (2023-03-15)

Features

  • changelog: send tagname to changelog function (#994) (95f526d)

0.25.1 (2023-01-09)

Bug Fixes

Note: this requires a git email and name to be set before trigger.

0.25.0 (2022-11-22)

Features

  • versioning: allow independent versioning (#984) (53f2f0b)

Bug Fixes

  • github: require later version of octokit (bb915bf)

0.24.4 (2022-04-12)

Bug Fixes

  • github: use non-deprecated requestReviewers function (#978) (be87a2c)

0.24.3 (2022-02-22)

Bug Fixes

  • get remote branches correctly when there are multiple origins (#974) (cbfe80d)

0.24.2 (2022-01-31)

Bug Fixes

  • deps: bump shelljs to ensure vuln fixed (#969) (aa72b45)

0.24.1 (2021-12-07)

Bug Fixes

0.24.0 (2021-09-21)

Features

0.23.3 (2021-06-14)

Bug Fixes

  • prepare: add missing version in the changelog (#954) (2a8e7c5)

0.23.2 (2021-04-12)

Bug Fixes

  • print out error when changelog fails (d40b041)

0.23.1 (2021-03-09)

Bug Fixes

  • prepare: allow shouldPrepare callback to run during --dry-run (#947) (8602ba0)

0.23.0 (2020-11-06)

BREAKING CHANGE

BREAKING CHANGE

If you don't use Ship.js in a monorepo, this breaking change doesn't affect you.

If you do, we have a good addition for you. Ship.js will update the versions of the dependencies in the monorepo. You can learn more from here.

Features

Bug Fixes

  • specify path for changelog (#673) (74531a3)
  • github-actions: use the actions/github-script action instead of the deprecated actions/github action (#934) (4f56bdb)

0.22.0 (2020-09-28)

Bug Fixes

Features

  • understands --config <FILE> option in conventionalChangelogArgs (#927) (06c7226)

0.21.1 (2020-09-23)

Bug Fixes

  • setup: add --tag to publish command in generated config (#916) (53121e2)
  • trigger: replace yarn publish with npm publish (#919) (66149dc)
  • trigger: set npm config to read NPM_AUTH_TOKEN (#923) (1c935a3)

0.21.0 (2020-08-24)

Features

0.20.1 (2020-06-22)

Bug Fixes

  • setup: improve GitHub Actions flow made with (#904) (066ff50)

0.20.0 (2020-06-16)

BREAKING CHANGE

BREAKING CHANGE

From this version, mergeStrategy no longer exists.

If you don't know what it is,

Make sure you run shipjs trigger only on the branches you've specified.

If you have a CircleCI config like the following:

version: 2
jobs:
  shipjs_trigger:
    docker:
      - image: "circleci/node:latest"
    steps:
      - checkout
      - run:
          name: Install
          command: yarn install
      - run:
          name: Triggering Ship.js to Release
          command: yarn shipjs trigger
workflows:
  version: 2
  release_if_needed:
    jobs:
      - shipjs_trigger

then, modify the last part like the following:

workflows:
  version: 2
  release_if_needed:
    jobs:
      - shipjs_trigger:
          filters:
            branches:
              only:
                - master # or whatever branch you'd like (normally your base branch)

This ensures shipjs trigger runs only on the specified branches.

If you were using mergeStrategy,

Ship.js used to have toSameBranch and toReleaseBranch strategies. Now they're gone and it only works like toSameBranch strategy. As explained above, you need to specify branches where to run shipjs trigger, though.

If you were using toReleaseBranch, there is a workaround. You can read Release Snapshot to achieve what you used to do.

Bug Fixes

  • prepare: return correct releaseType (#885) (7d918f6)
  • setup: get correct remote branches (#883) (551dde0)
  • setup: update circleci node version to v12 (#884) (6579294)
  • setup: use current branch when there is no remote at setup flow (#881) (5a0e152)

0.19.0 (2020-05-12)

Features

  • force push to protected branch with explicit config (#813) (3647853)

0.18.4 (2020-05-08)

Bug Fixes

  • actions: fix ejs syntax (#801) (8055a9f)
  • release: push to correct branch in toReleaseBranch strategy (#803) (1367315)

0.18.3 (2020-05-04)

Bug Fixes

  • actions: add fetch-depth and git fetch (#778) (994e4ff)
  • deps: update dependency shelljs to v0.8.4 (#776) (b70fc24)
  • release: skip running publishCommand if nullish (#793) (eb62c8d)

0.18.2 (2020-04-07)

Bug Fixes

  • prepare: fix wrong comparison url in the PR summary when getTagName is overridden in ship.config.js (#753) (4a40920)

0.18.1 (2020-04-03)

Bug Fixes

  • deps: update dependency prettier to v2 (#732) (96d6ff2)
  • prepare: respect custom tag name when getting a revision range (#751) (a1baa93)

0.18.0 (2020-03-17)

Bug Fixes

  • setup: use github-actions[bot] name and email for generated pull requests (#719) (ea4571e)

Features

  • prepare: add a new hook getNextVersion (#724) (21cf827)

0.17.0 (2020-03-06)

BREAKING CHANGE

BREAKING CHANGE

This version introduces some breaking changes.

  • In your ship.config.js, rename pullRequestReviewer to pullRequestReviewers (which accepts only an array of strings).

  • In your ship.config.js, rename pullRequestTeamReviewer to pullRequestTeamReviewers (which accepts only an array of strings).

  • releaseStart for Slack message has been removed. If you'd like to have it back, please create an issue and let's discuss.

  • The default value of testCommandBeforeRelease is now undefined. It used to be ({ isYarn }) => isYarn ? 'yarn test' : 'npm run test'. This change assumes many of you already run tests with CI services when you create pull requests. With the previous config, Ship.js unnecessarily ran tests before release. If you'd like to have it back, add some config like the following:

testCommandBeforeRelease: ({ isYarn }) => isYarn ? 'yarn test' : 'npm run test',

Bug Fixes

  • setup: do not write ship.config.js if not necessary (#705) (82f8cbc)
  • setup: fix wrong config(packagesToBump, packagesToPublish) for monorepo (#701) (0590a38)

  • clean up reviewer related configs (#707) (833d684)

  • allow @(a|b|c) syntax for packagesToBump and packagesToPublish (#702) (de9083c)
  • remove releaseStart hook for slack message (#703) (2a9502b)
  • create CHANGELOG if missing (#697) (72cb4ec)
  • empty testCommandBeforeRelease by default (#696) (34753b0)
  • shipjs-lib: exclude dependencies from final bundle (#651) (f6ec4cf)
  • check nullable value for reviewers (#709) (df7c0be)

0.16.1 (2020-03-03)

Bug Fixes

0.16.0 (2020-02-25)

Bug Fixes

Features

  • error: tell user where to create a GitHub token (#665) (901fcd8)

0.15.0 (2020-02-03)

Features

shouldPrepare

default: undefined

// example
shouldPrepare: ({
                  commits,
                  nextVersion,
                  releaseType,
                  releaseTag,
                  commitNumbersPerType,
               }) => { /* ... */ }

This is a lifecycle hook where you can decide whether or not to proceed with the preparation.

Read the guide to learn more about the hook.

0.14.2 (2020-01-27)

Bug Fixes

0.14.1 (2020-01-22)

Bug Fixes

releaseType

The following shows how releaseType is determined.

normal cases

  • 1.2.3 -> 2.0.0: major
  • 1.2.3 -> 1.3.0: minor
  • 1.2.3 -> 1.2.4: patch

next version has a tag

  • 1.2.3 -> 1.2.4-alpha.0: prerelease
  • 1.2.4-alpha.0 -> 1.2.4-alpha.1: prerelease

version with a tag -> version without one

  • 1.2.4-alpha.0 -> 1.2.4: patch
  • 1.2.4-alpha.0 -> 1.2.5: patch
  • 1.2.4-alpha.0 -> 1.3.0: minor
  • 1.2.4-alpha.0 -> 2.0.0: major
  • 1.3.0-alpha.0 -> 1.3.0: minor Just like normal cases, the new version decides the releaseType.

0.14.0 (2020-01-14)

Bug Fixes

  • release: add version in afterPublish hook (#608) (76c5591)
  • action: pin GitHub Action versions (#612) (b5e576a)
  • action: replace switch with build in checkout (#602) (ef5f8b9)
  • slack: use tag name instead of release tag (#609) (f183425)

Features

  • prepare: provide a config to assign team as reviewer (#619) (14ebf38)

0.13.1 (2019-12-31)

Bug Fixes

  • trigger: fix a bug it threw an exception at finished step (#581) (eb60e56)

0.13.0 (2019-12-31)

Bug Fixes

  • github-actions: fix image name (#557) (33f710c)
  • replace GH_TOKEN with GITHUB_TOKEN (#568) (835e26f)
  • prepare: throw with --yes when git tag is missing (#570) (cee5f35)

Features

  • prepare: add --commit-from option (#572) (041d3d9)
  • release: notify GitHub release url instead of CHANGELOG (#555) (c017067), closes #506

0.12.1 (2019-12-24)

Bug Fixes

  • setup: add SLACK_INCOMING_HOOK env for all GitHub Actions (#550) (dbdd919)
  • setup: don't use escape for config serializion (#549) (59b802d)

0.12.0 (2019-12-20)

Features

  • setup: add github actions as CI option (#502) (923cc87)

0.11.3 (2019-12-17)

Bug Fixes

  • drop conventional-changelog-cli and use its node library instead (#525) (430c303)

0.11.2 (2019-12-04)

Bug Fixes

prepare

  • add missing pr url to slack message (#499) (fa1e654)
  • make versionUpdated and beforeCommitChanges undefined by default (#495) (d9a4c51)

trigger

  • wrong release content due to wrong regexp (#484) (ba9588a)

setup

0.11.1 (2019-12-01)

Bug Fixes

prepare

  • ask commit range when tag is missing (#471) (f659c34)
  • clean up remote origin-with-token after git push (#479) (c81d247)
  • fetch tags before figuring out next version (#468) (045bbc0)
  • update changelog based on commit range (#473) (9841f25)
  • update PR message with publish command (#467) (18cc7e4)

trigger

setup

  • show master as a default branch when there is no remote yet (#466) (f079ba5)

0.11.0 (2019-11-27)

NOTICE

From 0.11.0, GITHUB_TOKEN is required as an environment variable for Ship.js to work.

Please refer to the guide.

Bug Fixes

  • check if origin-with-token already exists on prepare command (#455) (ce296a6)
  • create github release with rest api instead of hub (#458) (0bfeda6)
  • create pull request with rest api instead of hub (#456) (9423f11)
  • guide users to have GITHUB_TOKEN (#460) (b3ae436)
  • remove hub (#459) (cfd4b2f)

Features

0.10.0 (2019-11-26)

Bug Fixes

  • deprecate --first-release and --release-count at shipjs prepare (#447) (d46d83f)
  • pin dependency at shipjs setup (#446) (6560b9f)
  • getChangelog: wrong argument name (#448) (e378e06)

Features

  • releaseType: expose at hooks ("major", "minor", ...) (#441) (c855dbd)

0.9.0 (2019-11-25)

Bug Fixes

  • update path to conventional-changelog binary (#425) (75d9994)

Features

0.8.2 (2019-11-08)

Bug Fixes

  • continue release even if there's no conventional commit (#405) (70fb2ec)
  • fix hubConfigured for GitHub Actions (#393) (635ab7b)

0.8.1 (2019-11-05)

Bug Fixes

0.8.0 (2019-10-25)

Features

0.7.1 (2019-10-21)

Bug Fixes

  • skip creating a release at github when hub cli is not found (#353) (c408a00)

0.7.0 (2019-10-21)

Bug Fixes

Features

  • create GitHub releases (#311) (f1e4e77)
    • This is automatically done and uses the changelog as content of release.
  • upload assets to GitHub release (#334) (fcf2807)
    • At ship.config.js, You can configure releaeses.assetsToUpload. More details in configuration will come soon.

BREAKING CHANGE

BREAKING CHANGE

It's a breaking change but haven't bumped the major version since it's still in beta.

Please bear with any inconvenience.

  • replace monorepo.readVersionFrom with monorepo.mainVersionFile (#350) (107255a), (#351) (98617b4)
    • Now Ship.js updates the version at monorepo.mainVersionFile. With monorepo.readVersionFrom, it didn't update the file itself.

0.6.0 (2019-10-04)

Bug Fixes

  • don't display steps for slack when there's no slack config (#294) (eb1ab44)
  • fix pull request url in slack message (#301) (f89ba1d)

Features

  • add beforePublish and afterPublish hook (#293) (0de5d68)

0.5.5 (2019-10-01)

Bug Fixes

  • exit with 0 when there's nothing to release (#283) (3ef15fa)

0.5.4 (2019-09-25)

0.5.3 (2019-09-24)

0.5.2 (2019-09-24)

Bug Fixes

  • change formatCommitMessage and introduce formatPullRequestTitle (#270) (f21e167)

0.5.0 (2019-09-08)

Bug Fixes

  • add monorepo config (#246) (744cfc4)
  • fix a bug where it couldn't check correctly if hub is configured (#241) (c228772)
  • git push with upstream specified (#206) (ef5eccd)
  • print error message when hub doesn't exist (#205) (9ba45ff)
  • push to git with GITHUB_TOKEN (#234) (a39e7ee)
  • rename release command to trigger (#236) (3cbedb2)
  • throw when hub is installed but not configured (#208) (a4c769c)

Features

0.4.0 (2019-08-20)

Bug Fixes

Features

0.3.4 (2019-08-20)

0.3.2 (2019-08-18)

Bug Fixes

0.3.1 (2019-08-17)

Bug Fixes

  • ignore commits out of convention instead of throwing (#176) (b6fc850)

0.3.0 (2019-08-17)

Bug Fixes

  • deps: update dependency inquirer to v6.5.1 (#154) (040d722)

Features

0.2.0 (2019-08-07)

Bug Fixes

Features

  • reviewer: add config to assign reviewer when creating PR (#139) (4b7b74f)

0.1.0 (2019-08-02)

Initial Release