Want to find out how Shipkit works?
- see also getting started guide
- or the entire documentation index
Shipkit is a set of Gradle plugins. Shipkit works out of the box with Java libraries or Gradle plugin projects hosted on GitHub.
Shipkit integrates with:
- Travis CI (it's not difficult to use Shipkit with any CI)
- Bintray (that's how we push to Maven Central)
If you already have release process you can still leverage a specific feature of Shipkit. The best way to get started is to explain your use case to our team. Reach out by opening a ticket on GitHub
How do we:
- merge Pull Requests
- bump versions
- generate release notes
- publish binaries
- publishing binaries using maven-publish plugin
- avoid unnecessary releases
- support Android libraries
- shipping Javadoc
- automatically include contributors in pom.xml
Features we still work on:
If you look into ".travis.yml" file generated by Shipkit, you can find the following lines:
script:
- ./gradlew build -s && ./gradlew ciPerformRelease -sThose lines means the releasing process is two-stage.
First the build Gradle task is executed.
Shipkit doesn't change there a lot.
More interesting is the second task: ciPerformRelease.
This task depends on 3 another tasks: releaseNeeded, ciReleasePrepare and performRelease.
Let's looks closer to those tasks.
The following text image (created via textart.io) shows detailed sequence diagram. Text used to create this diagram: https://gist.github.com/mstachniuk/b7cfd3bef9fc1753c8759a2760505da9
+---------+ +---------+ +---------+ +-----+ +---------+
| Travis | | Gradle | | Shipkit | | Git | | Bintray |
+---------+ +---------+ +---------+ +-----+ +---------+
| | | | |
| Run gradlew ciPerformRelease | | | |
|------------------------------------------>| | | |
| | | | |
| | task identifyGitBranch | | |
| |------------------------------------------->| | |
| | | | |
| | Read env variable TRAVIS_BRANCH | | |
|<---------------------------------------------------------------------------------------| | |
| | | | |
| Return current branch name | | | |
|--------------------------------------------------------------------------------------->| | |
| | | | |
| | | read branch name (if TRAVIS_BRANCH doesn't exist) | |
| | |----------------------------------------------------->| |
| | | | |
| | | current branch name | |
| | |<-----------------------------------------------------| |
| | | | |
| | | | |
| |<-------------------------------------------| | |
| | | | |
| | task downloadPreviousReleaseArtifacts | | |
| |------------------------------------------->| | |
| | | | |
| | | Download previous sources jar | |
| | |-------------------------------------------------------------------------------------------------->|
| | | |------------------------------------------\ |
| | | || Gradle plugins will be published to |-|
| | | || Gradle Plugin Portal instead of Bintray | |
| | | ||-----------------------------------------| |
| | | | downloaded artifact |
| | |<--------------------------------------------------------------------------------------------------|
| | | | |
| | | | |
| |<-------------------------------------------| | |
| | | | |
| | task comparePublications | | |
| |------------------------------------------->| | |
| | | ----------------------------------------------\ | |
| | |-| - compare current dependencies with previous| | |
| | | | - compare current source jars with previous | | |
| | | | - store result into file | | |
| | read TRAVIS_BRANCH | |---------------------------------------------| | |
|<---------------------------------------------------------------------------------------| | |
| | | | |
| Return branch name | | | |
|--------------------------------------------------------------------------------------->| | |
| | | | |
| | | | |
| |<-------------------------------------------| | |
| | | | |
| | task releaseNeeded | | |
| |------------------------------------------->| | |
| | | | |
| | Check if env variable SKIP_RELEASE exist | | |
|<---------------------------------------------------------------------------------------| | |
| | | | |
| SKIP_RELEASE exist or not | | | |
|--------------------------------------------------------------------------------------->| | |
| | | | |
| | Read env variable TRAVIS_COMMIT_MESSAGE | | |
|<---------------------------------------------------------------------------------------| | |
| | | | |
| Return commit message | | | |
|--------------------------------------------------------------------------------------->| | |
| | | ----------------------------------------\ | |
| | |-| If PR merge commit message contains: | | |
| | | | - [ci skip-release] then skip release | | |
| | | | - [ci skip-compare-publications] then | | |
| | Check if build Pull Request | | ignore comparison result | | |
|<---------------------------------------------------------------------------------------| |---------------------------------------| | |
| -------------------------------------\ | | | |
|-| Actually it checks if env | | | | |
| | variable TRAVIS_PULL_REQUEST exist | | | | |
| |------------------------------------| | | | |
| | | | |
|--------------------------------------------------------------------------------------->| | |
| | | ------------------------------------------------\ | |
| | |-| Check if branch name match releaseBranchRegex | | |
| | | | (default: "master|release/.+") | | |
| | | -------------------------------------\----------| | |
| | |-| Check comparison results | | |
| | | | (if [ci skip-compare-publications] | | |
| | | | doesn't exist) | | |
| | Info is release needed or not | |------------------------------------| | |
| |<-------------------------------------------| | |
| | | | |
The following text image (created via textart.io) shows detailed sequence diagram. Text used to create this diagram: https://gist.github.com/mstachniuk/94d4972c193b0bb5c6500066f15171ae
+---------+ +---------+ +---------+ +-----+ +---------+ +---------+
| Travis | | Gradle | | Shipkit | | Git | | Bintray | | GitHub |
+---------+ +---------+ +---------+ +-----+ +---------+ +---------+
| | | | | |
| | task gitCheckout | | | |
| |-------------------------->| | | |
| | | | | |
| | | Checkout specific branch | | |
| | |------------------------------------>| | |
| | | | -----------------------------------------------------\ | |
| | | |-| CI server automatically checkout revision to build | | |
| | | | | (hash of the commit) instead of branch name | | |
| | | | | and branch name is lost. | | |
| | | | | Shipkit needs it for the next step. | | |
| |<----------------------------------------------------------------| | Execute e.g.: git checkout master | | |
| | | | |----------------------------------------------------| | |
| | task gitUnshallow | | | |
| |-------------------------->| | | |
| | | | | |
| | | Get sufficient amount of commits | | |
| | |------------------------------------>| | |
| | | | ------------------------------------------\ | |
| | | |-| CI server performs the unshallow clone. | | |
| | | | | We need a good number of commits to | | |
| | | | | generate release notes for. | | |
| | | | | Execute: git fetch --unshallow --tags | | |
| |<----------------------------------------------------------------| |-----------------------------------------| | |
| | | | | |
| | task setGitUserEmail | | | |
| |-------------------------->| | | |
| | | | | |
| | | Set locally Git user email | | |
| | |------------------------------------>| | |
| | | | --------------------------------------------------------\ | |
| | | |-| Execute: | | |
| | | | | git config --local user.email <[email protected]> | | |
| | | | |-------------------------------------------------------| | |
| | | | | |
| |<----------------------------------------------------------------| | |
| | | | | |
| | task setGitUserName | | | |
| |-------------------------->| | | |
| | | | | |
| | | Set locally Git user name | | |
| | |------------------------------------>| | |
| | | | -------------------------------------------\ | |
| | | |-| Execute: | | |
| | | | | git config --local user.name shipkit-org | | |
| | | | |------------------------------------------| | |
| | | | | |
| |<----------------------------------------------------------------| | |
| | | | | |
The following text image (created via textart.io) shows detailed sequence diagram. Text used to create this diagram: https://gist.github.com/mstachniuk/41ca2bd6cf115b6d636f529aa507b0b3
+---------+ +---------+ +---------+ +-----+ +---------+ +---------+
| Travis | | Gradle | | Shipkit | | Git | | Bintray | | GitHub |
+---------+ +---------+ +---------+ +-----+ +---------+ +---------+
| | | | | |
| | task bumpVersionFile | | | |
| |----------------------------------------------------------->| | | |
| | | --------------------------------------\ | | |
| | |-| Update values in version.properties | | | |
| | | |-------------------------------------| | | |
| | | | | |
| | | | | |
| |<-----------------------------------------------------------| | | |
| | | | | |
| | task identifyGitBranch | | | |
| |----------------------------------------------------------->| | | |
| | | --------------------------------------------------------\ | | |
| | |-| See above sequence for releaseNeeded for more details | | | |
| | | |-------------------------------------------------------| | | |
| | | | | |
| | | | | |
| |<-----------------------------------------------------------| | | |
| | | | | |
| | task fetchContributors | | | |
| |----------------------------------------------------------->| | | |
| | | | | |
| | | Fetching all GitHub contributors | | |
| | |---------------------------------------------------------------------------------------------------------------------------------------->|
| | | | | |
| | | | | |
| |<-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| | | | | |
| | task fetchReleaseNotes | | | |
| |----------------------------------------------------------->| | | |
| | | | | |
| | | Fetch data about changes from the last release | | |
| | |----------------------------------------------------------->| | |
| | | | ------------------------------------------------------\ | |
| | | |-| Execute: git log --pretty=%ad --date=iso v0.0.1 -n 1| | |
| | | | | git fetch origin +refs/tags/v0.0.1:refs/tags/v0.0.1 | | |
| | | | | git log v0.0.1..HEAD | | |
| | | | |-----------------------------------------------------| | |
| | |<-----------------------------------------------------------| | |
| | | | | |
| | | Get information about GitHub issues | | |
| | |---------------------------------------------------------------------------------------------------------------------------------------->|
| | | | | |
| | | | | |
| |<-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| | | | | |
| | task updateReleaseNotes | | | |
| |----------------------------------------------------------->| | | |
| | | -------------------------\ | | |
| | |-| Generate Release Notes | | | |
| | | |------------------------| | | |
| | | | | |
| | | | | |
| |<-----------------------------------------------------------| | | |
| | | | | |
| | task gitCommit | | | |
| |----------------------------------------------------------->| | | |
| | | | | |
| | | Commit release notes and version.properties | | |
| | |----------------------------------------------------------->| | |
| | | | | |
| | | | | |
| |<------------------------------------------------------------------------------------------------------------------------| | |
| | | | | |
| | task gitTag | | | |
| |----------------------------------------------------------->| | | |
| | | | | |
| | | Create tag | | |
| | |----------------------------------------------------------->| | |
| | | | ----------------------------------------------------------\ | |
| | | |-| Execute: | | |
| | | | | git tag -a v0.0.2 -m "Created new tag v0.0.2 [ci skip]" | | |
| | | | | [ci skip] for not triggering infinite build loop on CI | | |
| | | | |---------------------------------------------------------| | |
| |<------------------------------------------------------------------------------------------------------------------------| | |
| | | | | |
| | task gitPush | | | |
| |----------------------------------------------------------->| | | |
| | | | | |
| | | Push commit and tag | | |
| | |----------------------------------------------------------->| | |
| | | | ----------------------------------\ | |
| | | |-| GitHub write token is used here | | |
| | | | |---------------------------------| | |
| | | | | |
| | | | | |
| |<------------------------------------------------------------------------------------------------------------------------| | |
| | | | | |
| | task performGitPush | | | |
| |----------------------------------------------------------->| | | |
| | | ----------------------------------\ | | |
| | |-| This task only aggregate tasks: | | | |
| | | | - gitCommit | | | |
| | | | - gitTag | | | |
| | | | - gitPush | | | |
| |<-----------------------------------------------------------| |---------------------------------| | | |
| | ------------------------------------------------------\ | | | |
| |-| Only if org.shipkit.javadoc plugin is applied BEGIN | | | | |
| | |-----------------------------------------------------| | | | |
| | | | | |
| | task copyJavadocToStageVersionDir | | | |
| |----------------------------------------------------------->| | | |
| | | ----------------------------------------------\ | | |
| | |-| Copy unpacked Javadoc from JAR to stage dir | | | |
| | | | for each subproject | | | |
| | | |---------------------------------------------| | | |
| | | | | |
| |<-----------------------------------------------------------| | | |
| | | | | |
| | task refreshVersionJavadoc | | | |
| |----------------------------------------------------------->| | | |
| | | ---------------------------------------------------\ | | |
| | |-| Aggregate all copyJavadocToStageVersionDir tasks | | | |
| | | |--------------------------------------------------| | | |
| | | | | |
| | | | | |
| |<-----------------------------------------------------------| | | |
| | | | | |
| | task cloneJavadocRepo | | | |
| |----------------------------------------------------------->| | | |
| | | -----------------------------------------\ | | |
| | |-| Only if Javadoc stage dir is NOT empty | | | |
| | | | Clones to the repo dir | | | |
| | | |----------------------------------------| | | |
| | | | | |
| |<-----------------------------------------------------------| | | |
| | | | | |
| | task checkoutJavadocRepoBranch | | | |
| |----------------------------------------------------------->| | | |
| | | | | |
| | | | | |
| |<-----------------------------------------------------------| | | |
| | | | | |
| | task copyJavadocToStageCurrentDir | | | |
| |----------------------------------------------------------->| | | |
| | | ----------------------\ | | |
| | |-| For each subproject | | | |
| | | |---------------------| | | |
| | | | | |
| | | | | |
| |<-----------------------------------------------------------| | | |
| | | | | |
| | task refreshCurrentJavadoc | | | |
| |----------------------------------------------------------->| | | |
| | | ---------------------------------------------------\ | | |
| | |-| Aggregate all copyJavadocToStageCurrentDir tasks | | | |
| | | |--------------------------------------------------| | | |
| | | | | |
| | | | | |
| |<-----------------------------------------------------------| | | |
| | | | | |
| | task copyJavadocStageToRepoDir | | | |
| |----------------------------------------------------------->| | | |
| | | | | |
| | | | | |
| |<-----------------------------------------------------------| | | |
| | | | | |
| | task commitJavadoc | | | |
| |----------------------------------------------------------->| | | |
| | | | | |
| | | | | |
| |<-----------------------------------------------------------| | | |
| | | | | |
| | task pushJavadoc | | | |
| |----------------------------------------------------------->| | | |
| | | | | |
| | | | | |
| |<-----------------------------------------------------------| | | |
| | | | | |
| | task releaseJavadoc | | | |
| |----------------------------------------------------------->| | | |
| | | ------------------------------------------------\ | | |
| | |-| Aggregate all tasks needed to release Javadoc | | | |
| | | |-----------------------------------------------| | | |
| | | | | |
| | | | | |
| |<-----------------------------------------------------------| | | |
| | ----------------------------------------------------\ | | | |
| |-| Only if org.shipkit.javadoc plugin is applied END | | | | |
| | |---------------------------------------------------| | | | |
| | | | | |
| | task updateReleaseNotesOnGitHub | | | |
| |----------------------------------------------------------->| | | |
| | | ----------------------------------------------------\ | | |
| | |-| Upload release notes to GitHub Releases Page | | | |
| | | | E.g.: https://github.com/mockito/shipkit/releases | | | |
| | | |---------------------------------------------------| | | |
| | | | | |
| |<-----------------------------------------------------------| | | |
| | | -----------------------------------------------\ | | |
| | |-| Final check if property dryRun is set, e.g.: | | | |
| | | | ./gradlew performRelease -PdryRun | | | |
| | | | It's useful for local testing | | | |
| | task bintrayUpload | |----------------------------------------------| | | |
| |----------------------------------------------------------->| | | |
| | | | | |
| | | upload artifacts | | |
| | |---------------------------------------------------------------------------------------------------------------------------->| |
| | | | | |
| | | | Release shipped! Thank you for using Shipkit! | |
| |<-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
| | | | | |
| DONE | | | | |
|<----------| | | | |
| | | | | |
Thank you for reading! Questions or feedback? Start discussion by opening a ticket in GitHub!