Skip to content

Releasing workflow

Production Releases


Before you begin: Please make sure you are set up with pod trunk and your CocoaPods account is a contributor to both the Workflow and WorkflowUI pods. If you need to be added as a contributor, please open a ticket requesting access, and assign it to @apgar or @timdonnelly.


  1. Merge an update of the change log with the changes since the last release.

  2. Make sure you’re on the master branch (or fix branch, e.g. v0.1-fixes).

  3. Confirm that the kotlin build is green before committing any changes

    1
    (cd kotlin && ./gradlew build connectedCheck)
    

  4. In kotlin/gradle.properties, remove the -SNAPSHOT prefix from the VERSION_NAME property. E.g. VERSION_NAME=0.1.0

  5. Create a commit and tag the commit with the version number:

    1
    2
    git commit -am "Releasing v0.1.0."
    git tag v0.1.0
    

  6. Upload the kotlin artifacts:

    1
    (cd kotlin && ./gradlew clean build && ./gradlew uploadArchives --no-parallel --no-daemon)
    

Disabling parallelism and daemon sharing is required by the vanniktech maven publish plugin. Without those, the artifacts will be split across multiple (invalid) staging repositories.

  1. Publish to CocoaPods:

    1
    2
    bundle exec pod trunk push Workflow.podspec
    bundle exec pod trunk push WorkflowUI.podspec
    

  2. Bump the version

  3. Kotlin: Update the VERSION_NAME property in kotlin/gradle.properties to the new snapshot version, e.g. VERSION_NAME=0.2.0-SNAPSHOT.
  4. Swift: Update s.version in *.podspec to the new version, e.g. 0.2.0.

  5. Commit the new snapshot version:

    1
    git commit -am "Finish releasing v0.1.0."
    

  6. Push your commits and tag:

    1
    2
    3
    git push origin master
    # or git push origin fix-branch
    git push origin v0.1.0
    

  7. Create the release on GitHub:

  8. Go to the Releases page for the GitHub project.
  9. Click “Draft a new release”.
  10. Enter the tag name you just pushed.
  11. Title the release with the same name as the tag.
  12. Copy & paste the changelog entry for this release into the description.
  13. If this is a pre-release version, check the pre-release box.
  14. Hit “Publish release”.

  15. If this was a fix release, merge changes to the master branch:

    1
    2
    3
    4
    5
    git checkout master
    git reset --hard origin/master
    git merge --no-ff v0.1-fixes
    # Resolve conflicts. Accept master's versions of gradle.properties and podspecs.
    git push origin master
    

  16. Publish the website. See below.

Deploying the documentation website

Official Workflow documentation lives at https://squareup.github.io/workflow. The website content consists of three parts:

  1. Markdown documentation: Lives in the docs/ folder, and consists of a set of hand-written Markdown files that document high-level concepts. The static site generator mkdocs (with Material theming) is used to convert the Markdown to static, styled HTML.
  2. Kotlin API reference: Kdoc embedded in Kotlin source files is converted to GitHub-flavored Markdown by Dokka and then included in the statically-generated website.
  3. Swift API reference: Markup comments from Swift files are converted Markdown by Sourcedocs and then included in the statically-generated website.

Setting up the site generators

If you’ve already done this, you can skip to Deploying the website to production below.

Kotlin: Dokka

Dokka runs as a Gradle plugin, so you need to be able to build the Kotlin source with Gradle, but that’s it. To generate the docs manually, run:

1
2
cd kotlin
./gradlew dokka

Swift: Sourcedocs

Sourcedocs generates a Markdown site from Swift files. You need Ruby, rubygems, bundler (2.x), Xcode 10.2+, CocoaPods, and of course Sourcedocs itself, to run it. Assuming you’ve already got Xcode, Ruby, and rubygems set up, install the rest of the dependencies:

1
2
gem install bundler cocoapods
brew install sourcedocs

If that succeeded, you need to generate an Xcode project before running Sourcedocs:

1
2
3
4
cd swift/Samples/SampleApp/
bundle exec pod install
# If this is your first time running CocoaPods, that will fail and you'll need to run this instead:
#bundle exec pod install --repo-update

You can manually generate the docs to verify everything is working correctly by running:

1
2
3
4
#cd swift/Samples/SampleApp/
sourcedocs generate -- -scheme Workflow -workspace SampleApp.xcworkspace
sourcedocs generate -- -scheme WorkflowUI -workspace SampleApp.xcworkspace
sourcedocs generate -- -scheme WorkflowTesting -workspace SampleApp.xcworkspace

mkdocs

Mkdocs is written in Python, so you’ll need Python and pip in order to run it. Assuming those are set up, run:

1
pip install mkdocs mkdocs-material

Generate the site manually with:

1
mkdocs build

While you’re working on the documentation files, you can run the site locally with:

1
mkdocs serve

Deploying the website to production

Before deploying the website for real, you need to export our Google Analytics key in an environment variable so that it will get added to the HTML. Get the key from one of the project maintainers, then add the following to your .bashrc and re-source it:

1
export WORKFLOW_GOOGLE_ANALYTICS_KEY=UA-__________-1

Now you’re ready to publish the site! Just choose a tag or SHA to deploy from, and run:

1
2
3
./deploy_website.sh TAG_OR_SHA
# For example:
#./deploy_website.sh v0.18.0

This will clone the repo to a temporary directory, checkout the right SHA, build Kotlin and Swift API docs, generate HTML, and push the newly-generated content to the gh-pages branch on GitHub.

Validating Markdown

Since all of our high-level documentation is written in Markdown, we run a linter in CI to ensure we use consistent formatting. Lint errors will fail your PR builds, so to run locally, install markdownlint:

1
gem install mdl

Run the linter using the lint_docs.sh:

1
./lint_docs.sh

Rules can be configured by editing .markdownlint.rb.


Kotlin Notes

Development

To build and install the current version to your local Maven repository (~/.m2), run:

1
./gradlew clean installArchives

Deploying

Configuration

In order to deploy artifacts to a Maven repository, you’ll need to set 4 properties in your private Gradle properties file (~/.gradle/gradle.properties):

1
2
3
4
RELEASE_REPOSITORY_URL=<url of release repository>
SNAPSHOT_REPOSITORY_URL=<url of snapshot repository
SONATYPE_NEXUS_USERNAME=<username>
SONATYPE_NEXUS_PASSWORD=<password>

Snapshot Releases

To deploy a new snapshot release, you don’t need to update any properties. Just run:

1
./gradlew clean uploadArchives