Home | History | Annotate | Download | only in conscrypt 
      1 How to Create a Conscrypt Release
      2 ====================================
      3 
      4 One-Time Setup
      5 --------------
      6 
      7 These steps need to be performed once by each person doing releases.
      8 
      9 ### Platforms
     10 
     11 Conscrypt is built on Linux, Mac, and Windows, so ensure you have access to machines
     12 running all three.  The 1.0.0 release was made with the following configuration:
     13 
     14 * Ubuntu 14.04
     15 * MacOS Sierra (10.12)
     16 * Windows Server 2016
     17 
     18 ### Software
     19 
     20 The following software is necessary and may not be installed by default:
     21 
     22 <!-- TODO(flooey): Expand and link these, there's probably more -->
     23 * Linux: [Docker](https://www.docker.com/), [Android SDK](https://developer.android.com/studio/index.html)
     24 * MacOS: Java SDK
     25 * Windows: MSVC, git, yasm, Java
     26 
     27 ### Setup OSSRH and GPG
     28 
     29 If you haven't deployed artifacts to Maven Central before, you need to setup
     30 your OSSRH (OSS Repository Hosting) account and signing keys.
     31 - Follow the instructions on [this
     32   page](http://central.sonatype.org/pages/ossrh-guide.html) to set up an
     33   account with OSSRH.
     34   - You only need to create the account, not set up a new project
     35   - Contact a Conscrypt maintainer to add your account after you have created it.
     36 - Install GnuPG and [generate your key
     37   pair](https://www.gnupg.org/documentation/howtos.html).
     38 - [Publish your public key](https://www.gnupg.org/gph/en/manual.html#AEN464)
     39   to make it visible to the Sonatype servers
     40   (e.g. `gpg --keyserver pgp.mit.edu --send-key <key ID>`).
     41 
     42 ### Get the signing certificates
     43 
     44 Contact an existing Conscrypt maintainer to get the keystore containing the
     45 code signing certificate.
     46 
     47 ### Set up gradle.properties
     48 
     49 Add your OSSRH credentials, GPG key information, and the code signing keystore details
     50 to `$HOME/.gradle/gradle.properties`.
     51 
     52 ```
     53 signing.keyId=<8-character-public-key-id>
     54 signing.password=<key-password>
     55 signing.secretKeyRingFile=<your-home-directory>/.gnupg/secring.gpg
     56 
     57 signingKeystore=<path-to-keystore>
     58 signingPassword=<keystore-password>
     59 
     60 ossrhUsername=<ossrh-username>
     61 ossrhPassword=<ossrh-password>
     62 checkstyle.ignoreFailures=false
     63 ```
     64 
     65 Once Per Release Series Setup
     66 -----------------------------
     67 
     68 These steps need to be performed once per `X.Y` release series.
     69 
     70 ### Create the release branch
     71 
     72 We use a branch named `v<major>.<minor>.x` for all releases in a series.
     73 
     74 Create the branch and push it to GitHub:
     75 
     76 ```bash
     77 $ git checkout -b 1.0.x master
     78 $ git push upstream 1.0.x
     79 ```
     80 
     81 ### Update the master version
     82 
     83 Update the master branch's version to the next minor snapshot.
     84 
     85 ```bash
     86 $ git checkout -b bump-version master
     87 # Change version in build.gradle to X.Y+1-SNAPSHOT
     88 $ git commit -a -m 'Start X.Y+1 development cycle'
     89 # Push to GitHub and get reviewed like normal
     90 ```
     91 
     92 Making a New Release
     93 --------------------
     94 
     95 ### Cherry-pick changes from the master branch (optional)
     96 
     97 Cherry-pick any desired master changes since the branch was created.
     98 
     99 ```bash
    100 $ git checkout 1.0.x
    101 $ git cherry-pick <revision>
    102 ```
    103 
    104 ### Tag the release
    105 
    106 ```bash
    107 # Change version in build.gradle to this version's number
    108 $ git commit -a -m 'Preparing version 1.0.0'
    109 $ git tag -a 1.0.0 -m 'Version 1.0.0'
    110 ```
    111 
    112 ### Push to GitHub
    113 
    114 Push both the branch and the new tag to GitHub.
    115 
    116 ```bash
    117 $ git push upstream 1.0.x
    118 $ git push upstream 1.0.0
    119 ```
    120 
    121 ### Build the Linux OpenJDK Release
    122 
    123 The deployment for Linux uses [Docker](https://www.docker.com/) running
    124 CentOS 6.6 in order to ensure that we have a consistent deployment environment
    125 on Linux.
    126 
    127 1. From the conscrypt source directory:
    128 
    129    ```bash
    130    $ docker build -t conscrypt-deploy .
    131    ```
    132 1. Start a Docker container that has the deploy environment set up for you. The
    133    Conscrypt source is cloned into `/conscrypt`.
    134 
    135    ```bash
    136    $ docker run -it --rm=true conscrypt-deploy
    137    ```
    138 
    139    Note that the container will be deleted after you exit. Any changes you have
    140    made (e.g., copied configuration files) will be lost. If you want to keep the
    141    container, remove `--rm=true` from the command line.
    142 1. Copy your OSSRH credentials and GnuPG keys to your docker container. In Docker:
    143    ```
    144    # mkdir /root/.gradle
    145    ```
    146    Find the container ID in your bash prompt, which is shown as `[root@<container-ID> ...]`.
    147    In host:
    148    ```
    149    $ docker cp ~/.gnupg <container-ID>:/root/
    150    $ docker cp ~/.gradle/gradle.properties <container-ID>:/root/.gradle/
    151    $ docker cp <path to cert keystore> <container-ID>:/root/certkeystore
    152    ```
    153 
    154    You'll also need to update `signing.secretKeyRingFile` and `signingKeystore` in
    155    `/root/.gradle/gradle.properties` to point to `/root/.gnupg/secring.gpg` and
    156    `/root/certkeystore`, respectively.
    157 1. Create the initial build
    158    ```bash
    159    $ git checkout 1.0.x
    160    $ ./gradlew conscrypt-openjdk:build
    161    $ ./gradlew -Dorg.gradle.parallel=false uploadArchives
    162    ```
    163 1. Note the BoringSSL commit used for this build.
    164    ```bash
    165    $ cd /usr/src/boringssl
    166    $ git log -n 1
    167    ```
    168 1. Go to the OSSRH UI and note the ID of the new staging repository.  It should be in the 
    169    form of `orgconscrypt-NNNN`.
    170 
    171 ### Build the Mac and Windows OpenJDK Releases
    172 
    173 See [BUILDING](BUILDING.md) for instructions for setting up the build environment.
    174 
    175 1. Ensure BoringSSL is synced to the same revision as for the Linux build.
    176    ```bash
    177    $ git checkout <revision>
    178    $ cd build64
    179    $ ninja
    180    # For Windows only
    181    $ cd ..\build32
    182    $ ninja
    183    ```
    184 1. Build the code and upload it to the staging repository noted previously.
    185    ```bash
    186    $ ./gradlew conscrypt-openjdk:build
    187    $ ./gradlew conscrypt-openjdk:uploadArchives -Dorg.gradle.parallel=false -PrepositoryId=<repository-id>
    188    ```
    189    (Omit the `./` for the Windows build.)
    190 
    191 ### Close and Release the Staging Repository
    192 
    193 1. Navigate to the staging repository, open the contents, and ensure there are jars for
    194    each supported build environment: linux-x86_64, osx-x86_64, windows-x86, and windows-x86_64.
    195 1. Click the `close` button at the top of the staging repo list.
    196 1. After the automated checks are done, click the `release` button at the top of the staging repo list.
    197 
    198 You can see the complete process for releasing to Maven Central on the [OSSRH site]
    199 (http://central.sonatype.org/pages/releasing-the-deployment.html).
    200 
    201 It will take several hours for the jars to show up on [Maven Central](http://search.maven.org).
    202 
    203 ### Build the Android Release
    204 
    205 The Android build is not yet integrated into the Docker container, so on any machine with
    206 the Android SDK installed, do the following:
    207 
    208 1. Build the code.
    209    ```bash
    210    $ ./gradlew conscrypt-android:build
    211    $ ./gradlew conscrypt-android:uploadArchives -Dorg.gradle.parallel=false
    212    ```
    213 1. Visit the OSSRH site and close and release the repository.
    214 
    215 ### Build the Uber Jar
    216 
    217 Once the platform-specific jars have shown up on Maven Central, return to the Docker container
    218 and build the Uber jar.
    219 
    220 1. Build the code.
    221    ```bash
    222    $ ./gradlew conscrypt-openjdk-uber:build -Dorg.conscrypt.openjdk.buildUberJar=true
    223    $ ./gradlew conscrypt-openjdk-uber:uploadArchives -Dorg.gradle.parallel=false -Dorg.conscrypt.openjdk.buildUberJar=true
    224    ```
    225 1. Visit the OSSRH site and close and release the repository.
    226 
    227 ### Notify the Community
    228 
    229 Finally, document and publicize the release.
    230 
    231 1. Add [Release Notes](https://github.com/google/conscrypt/releases) for the new tag.
    232    The description should include any major fixes or features since the last release.
    233    You may choose to add links to bugs, PRs, or commits if appropriate.
    234 2. Post a release announcement to [conscrypt](https://groups.google.com/forum/#!forum/conscrypt)
    235    (`conscrypt (a] googlegroups.com`). The title should be something that clearly identifies
    236    the release (e.g.`Conscrypt <tag> Released`).
    237