Release instructions

Select a version

Stetho releases follow the <major>.<minor>.<micro> versioning scheme where major version numbers denote substantial rewrites or major architectural shifts, minor versions represent new features or major bug fixes, and micro versions for bug fixes or small maintenance releases.

The previous maintainer expected the next release version to be specified in gradle.properties, suffixed with -SNAPSHOT. This is merely a hint as to what the next version might be, actual features landed may cause this version number to change. It is acceptable for the -SNAPSHOT version to be decremented.

Smoke test

1. Make sure the full project builds:

   ./gradlew check connectedCheck
   ./gradlew installArchives
   

2. Smoke test the sample app:

   ./gradlew installDebug
   

3. If there are problems, abort the process and correct.

Release to GitHub

1. Make sure you have upstream and origin remotes setup properly:

   # git remote -v
   origin	git@github.com:jasta/stetho.git (fetch)
   origin	git@github.com:jasta/stetho.git (push)
   upstream	https://github.com/facebook/stetho.git (fetch)
   upstream	https://github.com/facebook/stetho.git (push)
   

2. Update to the latest code locally:

   # git checkout master
   # git remote update upstream
   # git reset --hard upstream/master
   

3. Sanity check by making sure the top commit is reasonably up-to-date:

   # git show HEAD
   

4. Start a release branch:

   # git checkout -b release-vX.Y.Z
   

5. Modify CHANGELOG.md by manually looking at changes from the previous release (typically the commits starting with "Merge pull request" provide sufficient information).

   # git log --format=oneline vX.Y.z..
   [ edit CHANGELOG.md accordingly ]
   # git add CHANGELOG.md
   # git commit -m 'Update CHANGELOG.md to vX.Y.Z'
   

6. Modify all README.md to reflect the new version (the old version appears multiple times and there may be multiple files using them!).

7. Modify gradle.properties to cause the new version to be picked by by Maven/Gradle (make sure to drop -SNAPSHOT!):

   VERSION_NAME=X.Y.Z
   

8. Officially bump the version:

   # git add -u
   # git commit -m 'Bump version to X.Y.Z'
   

9. Prepare a PR representing the release changes:

   # git push -u origin release-vX.Y.Z
   

10. Create the final release artifacts:

    # ./gradlew clean assemble
    # ./gradlew fatjarRelease
    

11. If there are problems, correct on a different branch with different PRs and then merge them into the release branch!

12. Officially create the PR on github and merge.

13. Go to https://github.com/facebook/stetho/releases and click "Draft a new release".

14. Associate the release to a new tag, "vX.Y.Z", and use the title "Release X.Y.Z". Leave the description section empty.

15. Attach the following JARs built locally:

    stetho-X.Y.Z-fatjar.jar
    stetho-X.Y.Z.jar
    stetho-okhttp-X.Y.Z.jar
    stetho-timber-X.Y.Z.jar
    stetho-urlconnection-X.Y.Z.jar
    stetho-js-rhino-X.Y.Z.jar
    

16. Save/submit the release.

Release to Maven Central

1. Make sure you have an account with Maven Central by signing up for a JIRA account at: https://issues.sonatype.org/.

2. Create and distribute a GPG key if you have not already done so on this machine: http://blog.sonatype.com/2010/01/how-to-generate-pgp-signatures-with-maven

3. Create a ~/.gradle/gradle.properties file with your credentials for Maven Central and your GPG key:

   repositoryUsername=<yourusername>
   repositoryPassword=<yourpassword>
   signing.keyId=<KEYID>
   signing.password=<keypassword>
   signing.secretKeyRingFile=/home/<username>/.gnupg/secring.gpg (probably)
   

4. Upload to the staging area using:

   # ./gradlew uploadArchives
   

5. Promote the staging release to a real release at: https://oss.sonatype.org/#stagingRepositories. Find the comfacebook-* artifact that matches your upload and select "Close" on the top bar. This step can take some time to verify the artifact. Once closed, a "Release" button will be available on the top bar to finalize the process.

6. Habitually refresh http://repo1.maven.org/maven2/com/facebook/stetho/stetho/ until the release appears.

7. Important - Remove the ~/.gradle.properties file or at least comment out the username/password! This is necessary because there doesn't seem to be a way to interactively prompt during ./gradlew uploadArchives or use SSH keys or anything like that.

Update the next -SNAPSHOT version

1. Edit gradle.properties and guess at the next version (usually just bumping the micro version number):

   VERSION_NAME=X.Y.ZZ-SNAPSHOT
   

2. Commit as a PR:

   git commit -m 'Update to X.Y.ZZ-SNAPSHOT'
   git push -u origin snapshot-X.Y.ZZ
   

3. Go to github and merge the PR.

Shout it!

Post to Google+ and Twitter using #androiddev! If it's a big release, ask for a retweet from @fbOpenSource.

Further reading

The release and branching strategy that Stetho uses is based on: http://nvie.com/posts/a-successful-git-branching-model/