From 483738e8bc57bb238f24f164978e332ac8640e30 Mon Sep 17 00:00:00 2001 From: nmittler Date: Mon, 8 Jun 2015 14:32:37 -0700 Subject: [PATCH] Reorganizing the deployment docs. --- DEPLOYING.md | 211 --------------------------------- RELEASING.md | 290 +++++++++++++++++++++++++++++++++++++++++++++ compiler/README.md | 6 +- 3 files changed, 293 insertions(+), 214 deletions(-) delete mode 100644 DEPLOYING.md create mode 100644 RELEASING.md diff --git a/DEPLOYING.md b/DEPLOYING.md deleted file mode 100644 index e3f696d832..0000000000 --- a/DEPLOYING.md +++ /dev/null @@ -1,211 +0,0 @@ -How to Deploy GRPC Java to Maven Central (for Maintainers Only) -=============================================================== - -Build Environments ------------------- -We deploy GRPC to Maven Central under the following systems: -- Ubuntu 14.04 with Docker 1.6.1 that runs CentOS 6.6 -- Windows 7 64-bit with MSYS2 with mingw32 and mingw64 -- Mac OS X 10.9.5 - -Other systems may also work, but we haven't verified them. - -Prerequisites -------------- - -### Setup OSSRH and Signing - -If you haven't deployed artifacts to Maven Central before, you need to setup -your OSSRH account and signing keys. -- Follow the instructions on [this - page](http://central.sonatype.org/pages/ossrh-guide.html) to set up an - account with OSSRH. -- (For release deployment only) Install GnuPG and [generate your key - pair](https://www.gnupg.org/documentation/howtos.html) -- Put your GnuPG key password and OSSRH account information in - ``/.gradle/gradle.properties``. - -``` -# You need the signing properties only if you are making release deployment -signing.keyId=<8-character-public-key-id> -signing.password= -signing.secretKeyRingFile=/.gnupg/secring.gpg - -ossrhUsername= -ossrhPassword= -checkstyle.ignoreFailures=false -``` - -### Build Protobuf -Protobuf libraries are needed for compiling the GRPC codegen. Despite that you -may have installed Protobuf on your system, you may want to build Protobuf -separately and install it under your personal directory, because - -1. The Protobuf version installed on your system may be different from what - GRPC requires. You may not want to pollute your system installation. -2. We will deploy both 32-bit and 64-bit versions of the codegen, thus require - both variants of Protobuf libraries. You don't want to mix them in your - system paths. - - -#### Linux with Docker -Build the ``protoc-artifacts`` image under the Protobuf source directory: -``` -protobuf$ docker build -t protoc-artifacts protoc-artifacts -``` - -#### Windows 64-bit with MSYS2 (Recommended for Windows) -Because the gcc shipped with MSYS2 doesn't support multilib, you have to -compile and deploy 32-bit and 64-bit binaries in separate steps. - -##### Under MinGW-w64 Win32 Shell -Compile and install 32-bit protobuf: -``` -protobuf$ ./configure --disable-shared --prefix=$HOME/protobuf-32 -protobuf$ make clean && make && make install -``` - -##### Under MinGW-w64 Win64 Shell -Compile and install 64-bit protobuf: -``` -protobuf$ ./configure --disable-shared --prefix=$HOME/protobuf-64 -protobuf$ make clean && make && make install -``` - - -#### Windows 64-bit with Cygwin64 (TODO: incomplete) -Because the MinGW gcc shipped with Cygwin64 doesn't support multilib, you have -to compile and deploy 32-bit and 64-bit binaries in separate steps. - -Compile and install 32-bit protobuf. ``-static-libgcc -static-libstdc++`` are -needed for ``protoc`` to be successfully run in the unit test. -``` -protobuf$ LDFLAGS="-static-libgcc -static-libstdc++" ./configure --host=i686-w64-mingw32 --disable-shared --prefix=$HOME/protobuf-32 -protobuf$ make clean && make && make install -``` - -Compile and install 64-bit protobuf: -``` -protobuf$ ./configure --host=x86_64-w64-mingw32 --disable-shared --prefix=$HOME/protobuf-64 -protobuf$ make clean && make && make install -``` - - -#### Mac -Please refer to [Protobuf -README](https://github.com/google/protobuf/blob/master/README.md) for how to -set up GCC and Unix tools on Mac. - -Mac OS X has been 64-bit-only since 10.7 and we are compiling for 10.7 and up. -We only build 64-bit artifact for Mac. - -Compile and install protobuf: -``` -protobuf$ CXXFLAGS="-m64" ./configure --disable-shared --prefix=$HOME/protobuf -protobuf$ make clean && make && make install -``` - -Build and Deploy ----------------- -You may want to open a shell dedicated for the following tasks, because you -will set a few environment variables which is only used in deployment. - - -### Setup Environment Variables - -Compilation of the codegen requires additional environment variables to locate -the header files and libraries of Protobuf. - -#### Linux -Build the ``grpc-java-deploy`` image: -``` -grpc-java$ docker build -t grpc-java-deploy compiler -``` - -Start a Docker container that has the deploy environment set up for you. The -gRPC source is cloned into ``/grpc-java``. -``` -$ docker run -it --rm=true grpc-java-deploy -``` -Note that the container will be deleted after you exit. Any changes you have -made (e.g., copied configuration files) will be lost. If you want to keep the -container, remove ``--rm=true`` from the command line. - -You need to copy your OSSRH credentials and GnuPG keys to your docker container. -Run ``ifconfig`` in the host, find the IP address of the ``docker0`` interface. -Then in docker: -``` -# scp -r @:./.gnupg ~/ -# mkdir ~/.gradle -# scp -r @:./.gradle/gradle.properties ~/.gradle -``` - -Since ``$HOME`` is ``/root`` in the Docker container, remember to update -``signing.secretKeyRingFile`` in the Docker copy of ``gradle.properties`` to -point to ``/root/.gnupg/secring.gpg`` - -#### Windows 64-bit with MSYS2 - -##### Under MinGW-w64 Win32 Shell - -``` -grpc-java$ export CXXFLAGS="-I$HOME/protobuf-32/include" \ - LDFLAGS="-L$HOME/protobuf-32/lib" -``` - -##### Under MinGW-w64 Win64 Shell -``` -grpc-java$ export CXXFLAGS="-I$HOME/protobuf-64/include" \ - LDFLAGS="-L$HOME/protobuf-64/lib" -``` - - -#### Mac -``` -grpc-java$ export CXXFLAGS="-I$HOME/protobuf/include" \ - LDFLAGS="$HOME/protobuf/lib/libprotobuf.a $HOME/protobuf/lib/libprotoc.a" -``` - - - -### Deploy the Entire Project - -The following command will build the whole project and upload it to Maven -Central. -``` -grpc-java$ ./gradlew clean build && ./gradlew uploadArchives -``` - -If the version has the ``SNAPSHOT`` suffix, the artifacts will automatically -go to the snapshot repository. Otherwise it's a release deployment and the -artifacts will go to a freshly created staging repository. - - -### Deploy GRPC Codegen for Additional Platforms -The previous step will only deploy the codegen artifacts for the OS you run on -it and the architecture of your JVM. For a fully fledged deployment, you will -need to deploy the codegen for all other supported OSes and architectures. - -To deploy the codegen for an OS and architecture, you must run the following -commands on that OS and specify the architecture by the flag ``-PtargetArch=``. - -We currently distribute the following OSes and architectures: -- Linux: ``x86_32``, ``x86_64`` -- Windows: ``x86_32``, ``x86_64`` -- Mac: ``x86_64`` - -If you are doing a snapshot deployment: -``` -grpc-java$ ./gradlew clean grpc-compiler:build grpc-compiler:uploadArchives -PtargetArch= -``` - -If you are doing a release deployment: -``` -grpc-java$ ./gradlew clean grpc-compiler:build grpc-compiler:uploadArchives -PtargetArch= \ - -PrepositoryId= -``` -where ```` is the ID of the staging repository that you have -found from the OSSRH UI after the first deployment, usually in the form of -``iogrpc-*``. This makes sure the additional codegen artifacts go to the same -repository as the main project is in. - diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 0000000000..6adaeb182b --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,290 @@ +How to Create a Release of GRPC Java (for Maintainers Only) +=============================================================== + +Build Environments +------------------ +We deploy GRPC to Maven Central under the following systems: +- Ubuntu 14.04 with Docker 1.6.1 that runs CentOS 6.6 +- Windows 7 64-bit with MSYS2 with mingw32 and mingw64 +- Mac OS X 10.9.5 + +Other systems may also work, but we haven't verified them. + +Prerequisites +------------- + +### Setup OSSRH and Signing + +If you haven't deployed artifacts to Maven Central before, you need to setup +your OSSRH (OSS Repository Hosting) account and signing keys. +- Follow the instructions on [this + page](http://central.sonatype.org/pages/ossrh-guide.html) to set up an + account with OSSRH. +- (For release deployment only) Install GnuPG and [generate your key + pair](https://www.gnupg.org/documentation/howtos.html). You'll also + need to [publish your public key](https://www.gnupg.org/gph/en/manual.html#AEN464) + to make it visible to the Sonatype servers + (e.g. `gpg --keyserver pgp.mit.edu --send-key `). +- Put your GnuPG key password and OSSRH account information in + `/.gradle/gradle.properties`. + +``` +# You need the signing properties only if you are making release deployment +signing.keyId=<8-character-public-key-id> +signing.password= +signing.secretKeyRingFile=/.gnupg/secring.gpg + +ossrhUsername= +ossrhPassword= +checkstyle.ignoreFailures=false +``` + +### Build Protobuf +Protobuf libraries are needed for compiling the GRPC codegen. Despite that you +may have installed Protobuf on your system, you may want to build Protobuf +separately and install it under your personal directory, because + +1. The Protobuf version installed on your system may be different from what + GRPC requires. You may not want to pollute your system installation. +2. We will deploy both 32-bit and 64-bit versions of the codegen, thus require + both variants of Protobuf libraries. You don't want to mix them in your + system paths. + +Please see the [Main Readme](README.md) for details on building protobuf. + +Tagging the Release +---------------------- +The first step in the release process is to create a release branch and then +from it, create a tag for the release. Our release branches follow the naming +convention of `v..x`, while the tags include the patch version +`v..`. For example, the same branch `v0.7.x` +would be used to create all `v0.7` tags (e.g. `v0.7.0`, `v0.7.1`). + +1. Create the release branch: + + ```bash + $ git checkout -b v..x master + ``` +2. Next, increment the version in `build.gradle` in `master` to the next + minor snapshot (e.g. ``0.8.0-SNAPSHOT``). +3. In the release branch, change the `build.gradle` to the next release version + (e.g. `0.7.0`) +4. Push the release branch to github + + ```bash + $ git push upstream v..x + ``` +5. In the release branch, create the release tag using the `Major.Minor.Patch` + naming convention: + + ```bash + $ git tag -a v.. + ``` +6. Push the release tag to github: + + ```bash + $ git push upstream v.. + ``` +7. Update the `build.gradle` in the release branch to point to the next patch + snapshot (e.g. `0.7.1-SNAPSHOT`). +8. Push the updated release branch to github. + + ```bash + $ git push upstream v..x + ``` + +Setup Build Environment +--------------------------- + +### Linux +The deployment for Linux uses [Docker](https://www.docker.com/) running +CentOS 6.6 in order to ensure that we have a consistent deployment environment +on Linux. You'll first need to install Docker if not already installed on your +system. + +1. Under the [Protobuf source directory](https://github.com/google/protobuf), + build the `protoc-artifacts` image: + + ```bash + protobuf$ docker build -t protoc-artifacts protoc-artifacts + ``` +2. Under the grpc-java source directory, build the `grpc-java-deploy` image: + + ```bash + grpc-java$ docker build -t grpc-java-deploy compiler + ``` +3. Start a Docker container that has the deploy environment set up for you. The + GRPC source is cloned into `/grpc-java`. + + ```bash + $ docker run -it --rm=true grpc-java-deploy + ``` + + Note that the container will be deleted after you exit. Any changes you have + made (e.g., copied configuration files) will be lost. If you want to keep the + container, remove `--rm=true` from the command line. +4. Next, you'll need to copy your OSSRH credentials and GnuPG keys to your docker container. + Run `ifconfig` in the host, find the IP address of the `docker0` interface. + Then in Docker: + + ```bash + $ scp -r @:./.gnupg ~/ + $ mkdir ~/.gradle + $ scp -r @:./.gradle/gradle.properties ~/.gradle + ``` + + You'll also need to update `signing.secretKeyRingFile` in + `/root/.gradle/gradle.properties` to point to `/root/.gnupg/secring.gpg`. + +### Windows + +#### Windows 64-bit with MSYS2 (Recommended for Windows) +Because the gcc shipped with MSYS2 doesn't support multilib, you have to +compile and deploy 32-bit and 64-bit binaries in separate steps. + +##### Under MinGW-w64 Win32 Shell +1. Compile and install 32-bit protobuf: + + ```bash + protobuf$ ./configure --disable-shared --prefix=$HOME/protobuf-32 + protobuf$ make clean && make && make install + ``` +2. Configure CXXFLAGS needed by the protoc plugin when building. + + ```bash + grpc-java$ export CXXFLAGS="-I$HOME/protobuf-32/include" \ + LDFLAGS="-L$HOME/protobuf-32/lib" + ``` + +##### Under MinGW-w64 Win64 Shell +1. Compile and install 64-bit protobuf: + + ```bash + protobuf$ ./configure --disable-shared --prefix=$HOME/protobuf-64 + protobuf$ make clean && make && make install + ``` +2. Configure CXXFLAGS needed by the protoc plugin when building. + + ```bash + grpc-java$ export CXXFLAGS="-I$HOME/protobuf-64/include" \ + LDFLAGS="-L$HOME/protobuf-64/lib" + ``` + +#### Windows 64-bit with Cygwin64 (TODO: incomplete) +Because the MinGW gcc shipped with Cygwin64 doesn't support multilib, you have +to compile and deploy 32-bit and 64-bit binaries in separate steps. + +1. Compile and install 32-bit protobuf. `-static-libgcc -static-libstdc++` are + needed for `protoc` to be successfully run in the unit test. + + ```bash + protobuf$ LDFLAGS="-static-libgcc -static-libstdc++" ./configure --host=i686-w64-mingw32 --disable-shared --prefix=$HOME/protobuf-32 + protobuf$ make clean && make && make install + ``` + +2. Compile and install 64-bit protobuf: + + ```bash + protobuf$ ./configure --host=x86_64-w64-mingw32 --disable-shared --prefix=$HOME/protobuf-64 + protobuf$ make clean && make && make install + ``` + +### Mac +Please refer to [Protobuf +README](https://github.com/google/protobuf/blob/master/README.md) for how to +set up GCC and Unix tools on Mac. + +Mac OS X has been 64-bit-only since 10.7 and we are compiling for 10.7 and up. +We only build 64-bit artifact for Mac. + +1. Compile and install protobuf: + + ```bash + protobuf$ CXXFLAGS="-m64" ./configure --disable-shared --prefix=$HOME/protobuf + protobuf$ make clean && make && make install + ``` +2. Configure CXXFLAGS needed by the protoc plugin when building. + + ```bash + grpc-java$ export CXXFLAGS="-I$HOME/protobuf/include" \ + LDFLAGS="$HOME/protobuf/lib/libprotobuf.a $HOME/protobuf/lib/libprotoc.a" + ``` + +Build and Deploy +---------------- +We currently distribute the following OSes and architectures: + +| OS | x86_32 | x86_64 | +| --- | --- | --- | +| Linux | X | X | +| Windows | X | X | +| Mac | | X | + +Deployment to Maven Central (or the snapshot repo) is a two-step process. The only +artifact that is platform-specific is codegen, so we only need to deploy the other +jars once. So the first deployment is for all of the artifacts from one of the selected +OS/architectures. After that, we then deploy the codegen artifacts for the remaining +OS/architectures. + +**NOTE: _Before building/deploying, be sure to switch to the appropriate branch or tag in +the grpc-java source directory._** + +### First Deployment + +As stated above, this only needs to be done once for one of the selected OS/architectures. +The following command will build the whole project and upload it to Maven +Central. +```bash +grpc-java$ ./gradlew clean build && ./gradlew uploadArchives +``` + +If the version has the `-SNAPSHOT` suffix, the artifacts will automatically +go to the snapshot repository. Otherwise it's a release deployment and the +artifacts will go to a freshly created staging repository. + +### Deploy GRPC Codegen for Additional Platforms +The previous step will only deploy the codegen artifacts for the OS you run on +it and the architecture of your JVM. For a fully fledged deployment, you will +need to deploy the codegen for all other supported OSes and architectures. + +To deploy the codegen for an OS and architecture, you must run the following +commands on that OS and specify the architecture by the flag `-PtargetArch=`. + +If you are doing a snapshot deployment: + +```bash +grpc-java$ ./gradlew clean grpc-compiler:build grpc-compiler:uploadArchives -PtargetArch= +``` + +When deploying a Release, the first deployment will create +[a new staging repository](https://oss.sonatype.org/#stagingRepositories). You'll need +to look up the ID in the OSSRH UI (usually in the form of `iogrpc-*`). Codegen +deployment commands should include `-PrepositoryId=` in order to +ensure that the artifacts are pushed to the same staging repository. + +```bash +grpc-java$ ./gradlew clean grpc-compiler:build grpc-compiler:uploadArchives -PtargetArch= \ + -PrepositoryId= +``` + +Releasing on Maven Central +-------------------------- +Once all of the artifacts have been pushed to the staging repository, the +repository must first be `closed`, which will trigger several sanity checks +on the repository. If this completes successfully, the repository can then +be `released`, which will begin the process of pushing the new artifacts to +Maven Central (the staging repository will be destroyed in the process). You can +see the complete process for releasing to Maven Central on the [OSSRH site] +(http://central.sonatype.org/pages/releasing-the-deployment.html). + +Notify the Community +-------------------- +After waiting ~1 day and verifying that the release appears on [Maven Central] +(http://mvnrepository.com/), the last step is to document and publicize the release. + +1. Add [Release Notes](https://github.com/grpc/grpc-java/releases) for the new tag. + The description should include any major fixes or features since the last release. + You may choose to add links to bugs, PRs, or commits if appropriate. +2. Post a release announcement to [grpc-io](https://groups.google.com/forum/#!forum/grpc-io) + (`grpc-io@googlegroups.com`). The title should be something that clearly identifies + the release (e.g.`GRPC-Java Released`). diff --git a/compiler/README.md b/compiler/README.md index df4a5b1425..10af9f0b28 100644 --- a/compiler/README.md +++ b/compiler/README.md @@ -51,6 +51,6 @@ repostiories. $ ../gradlew install ``` -## Pushing the codegen to Maven Central -Please follow the instructions in ``DEPLOYING.md`` under the root directory for -deploying the codegen to Maven Central. +## Creating a release of GRPC Java +Please follow the instructions in ``RELEASING.md`` under the root directory for +details on how to create a new release.