From e188bad268a24286e6c508120b4d86e15f6723c5 Mon Sep 17 00:00:00 2001 From: Carter Jernigan Date: Mon, 13 Jun 2022 13:59:38 -0400 Subject: [PATCH 1/4] [#66] Prepare for 1.0.3 release --- CHANGELOG.md | 12 +++++- docs/PUBLISHING.md | 92 ++++++++++++++++++++++++++++++++++++++++++++ docs/ci.md | 41 ++++++++++++++++++++ gradle.properties | 16 ++++++-- lib/build.gradle.kts | 10 ++++- 5 files changed, 164 insertions(+), 7 deletions(-) create mode 100644 docs/PUBLISHING.md create mode 100644 docs/ci.md diff --git a/CHANGELOG.md b/CHANGELOG.md index e80d434..3e6dc1a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,17 @@ Change Log ========== -Version 1.0.1 *(2020-09-19)* +Upcoming Version 1.0.3 +------------------------------------ +- Kotlin 1.6.21 +- Internal changes to support multiplatform in the future +- Snapshot builds are available prior to final release + +Version 1.0.2 +------------------------------------ +- Publish to Maven Central due to Jcenter deprecation + +Version 1.0.1 ------------------------------------ - First non-beta release! - New: Adds support for older devices that are missing crypto libraries. diff --git a/docs/PUBLISHING.md b/docs/PUBLISHING.md new file mode 100644 index 0000000..685df3a --- /dev/null +++ b/docs/PUBLISHING.md @@ -0,0 +1,92 @@ +# Overview +We aim for the main branch of the repository to always be in a releasable state. + +Two types of artifacts can be published: +1. Snapshot — An unstable release of the SDK for testing +1. Release — A stable release of the SDK + +Control of these modes of release is managed with a Gradle property `IS_SNAPSHOT`. + +For both snapshot and release publishing, there are two ways to initiate deployment: +1. Automatically +2. Manually + +This document will focus initially on the automated process, with a section at the end on manual process. (The automated process more or less implements the manual process via GitHub Actions.) + +# Automated Publishing +## Snapshots +All merges to the main branch trigger an automated [snapshot deployment](https://github.com/zcash/kotlin-bip39/actions/workflows/deploy-snapshot.yml). + +Note that snapshots do not have a stable API, so clients should not depend on a snapshot. The primary reason this is documented is for testing, e.g. before deploying a new production version of the library we may test against the snapshot first. + +Snapshots can be consumed by: + +1. Adding the snapshot repository +settings.gradle.kts: +``` +dependencyResolutionManagement { + repositories { + maven("https://oss.sonatype.org/content/repositories/snapshots") { + // Optional; ensures only explicitly declared dependencies come from this repository + content { + includeGroup("cash.z.ecc.android") + } + } + } +} +``` + +2. Changing the dependency version to end with `-SNAPSHOT` + +3. Rebuilding +`./gradlew assemble --refresh-dependencies` + +Because Gradle caches dependencies and because multiple snapshots can be deployed under the same version number, using `--refresh-dependencies` is important to ensure the latest snapshot is pulled. + +## Releases +Production releases can be consumed using the instructions in the [README.MD](../README.md). Note that production releases can include alpha or beta designations. + +Automated production releases still require a manual trigger. To do a production release: +1. Update the CHANGELOG and MIGRATIONS.md for any new changes since the last production release. +1. Run the [release deployment](https://github.com/zcash/kotlin-bip39/actions/workflows/deploy-release.yml). +1. Confirm deployment succeeded by modifying the [Secant Android Wallet](https://github.com/zcash/secant-android-wallet) to consume the new version. +1. Create a new Git tag for the new release in this repository. +1. Create a new pull request bumping the version to the next version (this ensures that the next merge to the main branch creates a snapshot under the next version number). + +# Manual Publishing +See [ci.md](ci.md), which describes the continuous integration workflow for deployment and describes the secrets that would need to be configured in a repository fork. + +## One time only +* Set up environment to [compile the SDK](https://github.com/zcash/zcash-android-wallet-sdk/#compiling-sources) +* Copy the GPG key to a directory with proper permissions (chmod 600). Note: If you'd like to quickly publish locally without subsequently publishing to Maven Central, configure a Gradle property `RELEASE_SIGNING_ENABLED=false` +* Create file `~/.gradle/gradle.properties` per the [instructions in this guide](https://proandroiddev.com/publishing-a-maven-artifact-3-3-step-by-step-instructions-to-mavencentral-publishing-bd661081645d) + * add your sonotype credentials with these properties + * `mavenCentralUsername` + * `mavenCentralPassword` + * point it to the GPG key with these properties + * `signing.keyId` + * `signing.password` + * `signing.secretKeyRingFile` + +## Every time +1. Update the [build number](https://github.com/zcash/zcash-android-wallet-sdk/blob/master/gradle.properties) and the [CHANGELOG](https://github.com/zcash/zcash-android-wallet-sdk/blob/master/CHANGELOG.md). For release builds, suffix the Gradle invocations below with `-PIS_SNAPSHOT=false`. +3. Build locally + * This will install the files in your local maven repo at `~/.m2/repository/cash/z/ecc/android/` +```zsh +./gradlew publishToMavenLocal +``` +4. Publish via the following command: +```zsh +# This uploads the file to sonotype’s staging area +./gradlew publish --no-daemon --no-parallel +``` +5. Deploy to maven central: +```zsh +# This closes the staging repository and releases it to the world +./gradlew closeAndReleaseRepository +``` + +Note: +Our existing artifacts can be found here and here: +https://search.maven.org/artifact/cash.z.ecc.android/kotlin-bip39 + diff --git a/docs/ci.md b/docs/ci.md new file mode 100644 index 0000000..a79f046 --- /dev/null +++ b/docs/ci.md @@ -0,0 +1,41 @@ +# Continuous Integration +Continuous integration is set up with GitHub Actions. The workflows are defined in this repo under [/.github/workflows](../.github/workflows). + +Workflows exist for: + * Pull request - On pull request, static analysis and testing is performed. + * Snapshot deployment - On merge to the main branch, a snapshot release is deployed to Maven Central. Concurrency limits are in place, to ensure that only one snapshot deployment can happen at a time. + * Release deployment - Manually invoked workflow to deploy to Maven Central. Concurrency limits are in place, to ensure that only one release deployment can happen at a time. + * Unwedge — If Snapshot deployment fails, it will often be due to multiple unclosed repositories. This workflow can take a given open repository name and attempt to close it. + +## Setup +When forking this repository, some secrets need to be defined to set up new continuous integration builds. + +The secrets passed to GitHub Actions then map to Gradle properties set up within our build scripts. Necessary secrets are documented at the top of each GitHub workflow yml file, as well as reiterated here. + +### Pull request +No configuration is required. + +### Snapshot deployment +* `MAVEN_CENTRAL_USERNAME` — Username for Maven Central, which maps to the Gradle property `mavenCentralUsername`. +* `MAVEN_CENTRAL_PASSWORD` — Password for Maven Central, which maps to the Gradle property `mavenCentralPassword`. + +GPG keys are not needed for snapshot deployment. + +Note: For documentation on the Gradle properties for Maven deployment, see [Gradle Maven Publish Plugin](https://github.com/vanniktech/gradle-maven-publish-plugin). + +Note: Snapshot builds are configured with a Gradle property `IS_SNAPSHOT`. The workflow automatically sets this property to true for snapshot deployments. This will suffix the version with `-snapshot` and will upload to the snapshot repository. + +### Release deployment +* `MAVEN_CENTRAL_USERNAME` — Username for Maven Central, which maps to the Gradle property `mavenCentralUsername`. +* `MAVEN_CENTRAL_PASSWORD` — Password for Maven Central, which maps to the Gradle property `mavenCentralPassword`. +* `MAVEN_SIGNING_KEYRING_FILE_BASE64` — GPG keyring file, base64 encoded. Maps to Gradle property `signing.secretKeyRingFile`. +* `MAVEN_SIGNING_KEY_ID` — Name of key inside GPG keyring file. Maps to Gradle property `signing.keyId`. +* `MAVEN_SIGNING_PASSWORD` — Password for key inside GPG keyring file. Maps to Gradle property `signing.password`. + +Note: For documentation on the Gradle properties for Maven deployment, see [Gradle Maven Publish Plugin](https://github.com/vanniktech/gradle-maven-publish-plugin). + +Note: Snapshot builds are configured with a Gradle property `IS_SNAPSHOT`. The workflow automatically sets this property to false for release deployments. + +### Unwedge +* `MAVEN_CENTRAL_USERNAME` — Username for Maven Central, which maps to the Gradle property `mavenCentralUsername`. +* `MAVEN_CENTRAL_PASSWORD` — Password for Maven Central, which maps to the Gradle property `mavenCentralPassword`. \ No newline at end of file diff --git a/gradle.properties b/gradle.properties index aea0ca7..15db646 100644 --- a/gradle.properties +++ b/gradle.properties @@ -15,9 +15,17 @@ JVM_TOOLCHAIN=17 JVM_TARGET=1.8 # Publishing : Required +## Configure these with command line arguments (`-PmavenCentralUsername=`), environment variables (`ORG_GRADLE_PROJECT_mavenCentralUsername`), or global ~/.gradle/gradle.properties +## Don't rename these, as they have special meaning in the com.vanniktech.maven.publish plugin and are used implicitly by it +mavenCentralUsername= +mavenCentralPassword= + +# Configures whether release is an unstable snapshot. +IS_SNAPSHOT=true + GROUP=cash.z.ecc.android POM_ARTIFACT_ID=kotlin-bip39 -VERSION_NAME=1.0.2 +VERSION_NAME=1.0.3 # Publishing : Optional POM_NAME=Kotlin BIP-39 @@ -30,8 +38,8 @@ POM_SCM_DEV_CONNECTION=scm:git:ssh://git@github.com/zcash/kotlin-bip39.git POM_LICENCE_NAME=The MIT License POM_LICENCE_URL=http://opensource.org/licenses/MIT POM_LICENCE_DIST=repo -POM_DEVELOPER_ID=gmale -POM_DEVELOPER_NAME=Kevin Gorham -POM_DEVELOPER_URL=https://github.com/gmale/ +POM_DEVELOPER_ID=zcash +POM_DEVELOPER_NAME=Zcash +POM_DEVELOPER_URL=https://github.com/zcash/ KOTLIN_VERSION=1.6.21 \ No newline at end of file diff --git a/lib/build.gradle.kts b/lib/build.gradle.kts index 6540154..5770b64 100644 --- a/lib/build.gradle.kts +++ b/lib/build.gradle.kts @@ -7,8 +7,14 @@ plugins { id("bip39.dependency-conventions") } -group = project.property("GROUP").toString() -version = project.property("VERSION_NAME").toString() +project.group = project.property("GROUP").toString() + +val libraryVersion = project.property("VERSION_NAME").toString() +project.version = if (project.property("IS_SNAPSHOT").toString().toBoolean()) { + "$version-SNAPSHOT" +} else { + version +} kotlin { jvm { From e5f667d4d74c7946fddd2483344fd319855097d8 Mon Sep 17 00:00:00 2001 From: Honza Date: Tue, 14 Jun 2022 09:21:23 +0200 Subject: [PATCH 2/4] Fix links to Bip39 project. Remove mentioned MIGRATIONS.md. --- docs/PUBLISHING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/PUBLISHING.md b/docs/PUBLISHING.md index 685df3a..c50fcb7 100644 --- a/docs/PUBLISHING.md +++ b/docs/PUBLISHING.md @@ -47,7 +47,7 @@ Because Gradle caches dependencies and because multiple snapshots can be deploye Production releases can be consumed using the instructions in the [README.MD](../README.md). Note that production releases can include alpha or beta designations. Automated production releases still require a manual trigger. To do a production release: -1. Update the CHANGELOG and MIGRATIONS.md for any new changes since the last production release. +1. Update the [CHANGELOG.MD](../CHANGELOG.md) for any new changes since the last production release. 1. Run the [release deployment](https://github.com/zcash/kotlin-bip39/actions/workflows/deploy-release.yml). 1. Confirm deployment succeeded by modifying the [Secant Android Wallet](https://github.com/zcash/secant-android-wallet) to consume the new version. 1. Create a new Git tag for the new release in this repository. @@ -69,7 +69,7 @@ See [ci.md](ci.md), which describes the continuous integration workflow for depl * `signing.secretKeyRingFile` ## Every time -1. Update the [build number](https://github.com/zcash/zcash-android-wallet-sdk/blob/master/gradle.properties) and the [CHANGELOG](https://github.com/zcash/zcash-android-wallet-sdk/blob/master/CHANGELOG.md). For release builds, suffix the Gradle invocations below with `-PIS_SNAPSHOT=false`. +1. Update the [build number](https://github.com/zcash/kotlin-bip39/blob/main/gradle.properties) and the [CHANGELOG](https://github.com/zcash/kotlin-bip39/blob/main/CHANGELOG.md). For release builds, suffix the Gradle invocations below with `-PIS_SNAPSHOT=false`. 3. Build locally * This will install the files in your local maven repo at `~/.m2/repository/cash/z/ecc/android/` ```zsh From 15bec79a3e7c5ae42f9df8a561d9d3da14e62690 Mon Sep 17 00:00:00 2001 From: Carter Jernigan Date: Tue, 14 Jun 2022 07:19:45 -0400 Subject: [PATCH 3/4] SDK -> library --- docs/PUBLISHING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/PUBLISHING.md b/docs/PUBLISHING.md index c50fcb7..04103e2 100644 --- a/docs/PUBLISHING.md +++ b/docs/PUBLISHING.md @@ -2,8 +2,8 @@ We aim for the main branch of the repository to always be in a releasable state. Two types of artifacts can be published: -1. Snapshot — An unstable release of the SDK for testing -1. Release — A stable release of the SDK +1. Snapshot — An unstable release of the library for testing +1. Release — A stable release of the library Control of these modes of release is managed with a Gradle property `IS_SNAPSHOT`. From 83272692002a733cba1f3e6582b0234567ec10ed Mon Sep 17 00:00:00 2001 From: Carter Jernigan Date: Tue, 14 Jun 2022 07:21:03 -0400 Subject: [PATCH 4/4] Remove reference to Zcash Android SDK --- docs/PUBLISHING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/PUBLISHING.md b/docs/PUBLISHING.md index 04103e2..3c07197 100644 --- a/docs/PUBLISHING.md +++ b/docs/PUBLISHING.md @@ -57,7 +57,7 @@ Automated production releases still require a manual trigger. To do a productio See [ci.md](ci.md), which describes the continuous integration workflow for deployment and describes the secrets that would need to be configured in a repository fork. ## One time only -* Set up environment to [compile the SDK](https://github.com/zcash/zcash-android-wallet-sdk/#compiling-sources) +* Set up environment to compile the library * Copy the GPG key to a directory with proper permissions (chmod 600). Note: If you'd like to quickly publish locally without subsequently publishing to Maven Central, configure a Gradle property `RELEASE_SIGNING_ENABLED=false` * Create file `~/.gradle/gradle.properties` per the [instructions in this guide](https://proandroiddev.com/publishing-a-maven-artifact-3-3-step-by-step-instructions-to-mavencentral-publishing-bd661081645d) * add your sonotype credentials with these properties