RELEASING.md

Releasing workflow

Production Releases

---

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

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

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

   ./gradlew build connectedCheck

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

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

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

6. Upload the kotlin artifacts:

   ./gradlew clean build && ./gradlew uploadArchives --no-parallel

   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. (Note that uploadArchives is deprecated in favor of publish, but publish makes bad artifacts.)

7. Close and release the staging repository at https://oss.sonatype.org/#stagingRepositories.

8. Bump the version

   • Kotlin: Update the VERSION_NAME property in gradle.properties to the new snapshot version, e.g. VERSION_NAME=0.2.0-SNAPSHOT.

9. Commit the new snapshot version:

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

10. Push your commits and tag:

    git push origin main
    # or git push origin fix-branch
    git push origin v0.1.0
    

11. Create the release on GitHub:

    1. Go to the Releases page for the GitHub project.
    2. Click "Draft a new release".
    3. Enter the tag name you just pushed.
    4. Title the release with the same name as the tag.
    5. Copy & paste the changelog entry for this release into the description.
    6. If this is a pre-release version, check the pre-release box.
    7. Hit "Publish release".

12. If this was a fix release, merge changes to the main branch:

    git checkout main
    git pull
    git merge --no-ff v0.1-fixes
    # Resolve conflicts. Accept main's versions of gradle.properties and podspecs.
    git push origin main

13. Publish the documentation website, https://github.com/square/workflow

    1. Run the Publish Documentation Site action, providing a personal branch name in the last field (e.g. yourname/kotlin-v0.1.0).
    2. Pull the created branch and merge it into gh-pages
       1. git fetch --all
       2. git co gh-pages
       3. git merge --no-ff origin/yourname/kotlin-v0.1.0
       4. git push origin gh-pages

14. Once Maven artifacts are synced, update the workflow version used by the tutorial in samples/tutorial/build.gradle.

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:

gem install mdl

Run the linter using the lint_docs.sh:

./lint_docs.sh

Rules can be configured by editing .markdownlint.rb.

---

Notes

Development

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

./gradlew clean publishToMavenLocal

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):

RELEASE_REPOSITORY_URL=<url of release repository>
SNAPSHOT_REPOSITORY_URL=<url of snapshot repository
mavenCentralUsername=<username>
mavenCentralPassword=<password>

Snapshot Releases

Double-check that gradle.properties correctly contains the -SNAPSHOT suffix, then upload snapshot artifacts to Sonatype just like you would for a production release:

./gradlew clean build && ./gradlew uploadArchives --no-parallel

You can verify the artifacts are available by visiting https://oss.sonatype.org/content/repositories/snapshots/com/squareup/workflow/.