Added more release manager docs CTR
Project: http://git-wip-us.apache.org/repos/asf/tinkerpop/repo Commit: http://git-wip-us.apache.org/repos/asf/tinkerpop/commit/90e74768 Tree: http://git-wip-us.apache.org/repos/asf/tinkerpop/tree/90e74768 Diff: http://git-wip-us.apache.org/repos/asf/tinkerpop/diff/90e74768 Branch: refs/heads/TINKERPOP-1956 Commit: 90e747688a860fdcbe5ae52d025144e52c9f4f4c Parents: cc7d2e2 Author: Stephen Mallette <sp...@genoprime.com> Authored: Mon May 14 10:55:18 2018 -0400 Committer: Stephen Mallette <sp...@genoprime.com> Committed: Mon May 14 10:55:18 2018 -0400 ---------------------------------------------------------------------- .../developer/development-environment.asciidoc | 56 ++++++++++---------- docs/src/dev/developer/release.asciidoc | 46 ++++++++-------- 2 files changed, 51 insertions(+), 51 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/90e74768/docs/src/dev/developer/development-environment.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/dev/developer/development-environment.asciidoc b/docs/src/dev/developer/development-environment.asciidoc index 3e3edad..4dfbcaa 100644 --- a/docs/src/dev/developer/development-environment.asciidoc +++ b/docs/src/dev/developer/development-environment.asciidoc @@ -97,6 +97,8 @@ integration tests and therefore must be actively switched on with `-DskipIntegra [source,text] mvn clean install -pl gremlin-console -DskipIntegrationTests=false +See the <<release-environment,Release Environment>> section for more information on release manager configurations. + [[dotnet-environment]] === DotNet Environment @@ -114,33 +116,16 @@ and `test` directories of the `gremlin-dotnet` module  which will signify to Ma The `.glv` file need not have any contents and is ignored by Git. A standard `mvn clean install` will then build `gremlin-dotnet` in full. -For those who will release TinkerPop, it is also necessary to install link:http://www.mono-project.com/[Mono]. The -release process is known to work with 5.0.1, so it is best to probably install that version. Release managers should -probably also do an install of link:https://dist.nuget.org/win-x86-commandline/v3.4.4/nuget.exe[nuget 3.4.4] as it -will help with environmental setup. To get an environment ready to deploy to NuGet, it is necessary to have a -NuGet API key (PMC members who have NuGet accounts can help with that). The API key should be added to `NuGet.Config` -with the following: - -[source,text] ----- -mono nuget.exe setApiKey [your-api-key] ----- - -This should update `~/.config/NuGet/NuGet.Config` a file with an entry containing the encrypted API key. On -`mvn deploy`, this file will be referenced on the automated `nuget push`. - -See release documentation for more information on configuration for release. - +See the <<release-environment,Release Environment>> section for more information on release manager configurations. [[nodejs-environment]] === JavaScript Environment + When building `gremlin-javascript`, mvn command will include a local copy of Node.js runtime and npm inside your project using `com.github.eirslett:frontend-maven-plugin` plugin. This copy of the Node.js runtime will not affect any other existing Node.js runtime instances in your machine. -The release manager should have the authentication token set, for more information see the Release Environment -section below. - +See the <<release-environment,Release Environment>> section for more information on release manager configurations. [[release-environment]] === Release Environment @@ -152,9 +137,9 @@ link:https://dist.apache.org/repos/dist/dev/tinkerpop/KEYS[development] and link:https://dist.apache.org/repos/dist/release/tinkerpop/KEYS[release] distribution directories and committed using Apache Subversion (SVN). -Uploading to pypi uses link:https://pypi.python.org/pypi/twine[twine] which is automatically installed by the build -process in maven. Twine refers to `HOME/.pypirc` file for configuration on the pypi deploy environments and username -and password combinations. The file typically looks like this: +For Python releases, uploading to pypi uses link:https://pypi.python.org/pypi/twine[twine] which is automatically +installed by the build process in maven. Twine refers to `HOME/.pypirc` file for configuration on the pypi deploy +environments and username and password combinations. The file typically looks like this: [source,text] ---- @@ -164,7 +149,6 @@ index-servers= pypitest [pypitest] -repository = https://testpypi.python.org/pypi username = <username> password = @@ -174,12 +158,30 @@ username = <username> password = ---- -The release manager shall use the project's pypi credentials, which are available in the PMC repository. -The `password` should be left blank so the deployment process in Maven will prompt for it at deployment time. +The release manager shall use the project's pypi credentials, which are available in the +link:https://svn.apache.org/repos/private/pmc/tinkerpop[PMC SVN repository]. The `password` should be left blank so +the deployment process in Maven will prompt for it at deployment time. + +For .NET releases, install link:http://www.mono-project.com/[Mono]. The release process is known to work with 5.0.1, +so it is best to probably install that version. Release managers should probably also do an install of +link:https://dist.nuget.org/win-x86-commandline/v3.4.4/nuget.exe[nuget 3.4.4] as it will help with environmental setup. +To get an environment ready to deploy to NuGet, it is necessary to have a NuGet API key. First, create an account with +link:https://www.nuget.org[nuget] and request that a PMC member add your account to the Gremlin.Net package in nuget +so that you can deploy. Next, generate an API key for your account on the nuget website. The API key should be added +to `NuGet.Config` with the following: + +[source,text] +---- +mono nuget.exe setApiKey [your-api-key] +---- + +This should update `~/.config/NuGet/NuGet.Config` a file with an entry containing the encrypted API key. On +`mvn deploy`, this file will be referenced on the automated `nuget push`. To deploy `gremlin-javascript` on the link:https://www.npmjs.com[npm registry], the release manager must set the authentication information on the ~/.npmrc file. The easiest way to do that is to use the `npm adduser` command. This -must be done only once, as the auth token doesn't have an expiration date and it's stored on your file system. +must be done only once, as the auth token doesn't have an expiration date and it's stored on your file system. If +this account is newly created then request that a PMC member add your account to the "gremlin" package on npm. [[building-testing]] == Building and Testing http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/90e74768/docs/src/dev/developer/release.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/dev/developer/release.asciidoc b/docs/src/dev/developer/release.asciidoc index 1a7ef82..8631a74 100644 --- a/docs/src/dev/developer/release.asciidoc +++ b/docs/src/dev/developer/release.asciidoc @@ -27,18 +27,16 @@ feedback. Once a release point has been identified, the following phases repres * Submit the official release for PMC vote. * Release and promote. -NOTE: It might be helpful to use this document as generated from the currently release as opposed to one generate -from a previous version or from recent `SNAPSHOT`. When using one generated for release, all the "versions" in the -commands end up being set to the version that is being released, making cut and paste of those commands less labor -intensive and error prone. +IMPORTANT: During release, it is best to use the current SNAPSHOT version of this documentation to ensure that you have +the latest updates as almost every release includes improved documentation that may involve new or revised steps to +execute. IMPORTANT: The following instructions assume that the release manager's <<development-environment,environment>> is setup -properly for release and includes a `.glv` file in `gremlin-python` as described in the <<python-environment,Python Environment>> -section, so that the `gremlin-python` module builds in full. +properly for release and includes a `.glv` files in the various GLV modules, so that they all build in full. === Development Versions -A "development version" or snapshot (in Java parlance) is not an "official" release. Artifacts produced for a +A "development version" or "snapshot" (in Java parlance) is not an "official" release. Artifacts produced for a snapshot are solely for the convenience of providers and other developers who want to use the latest releases of TinkerPop. These releases do not require a VOTE and do not require a "release manager". Any PMC member can deploy them. It is important to note that these releases cannot be promoted outside of the developer mailing list and should not be @@ -51,34 +49,32 @@ For JVM-based artifacts, simply use the following command: [source,text] mvn clean deploy -and artifacts will be pushed to the link:http://repository.apache.org/snapshots/[Apache Snapshot Repository]. Python +and artifacts will be pushed to the link:http://repository.apache.org/snapshots/[Apache Snapshot Repository]. GLV development artifacts must be generated and deployed separately with additional commands: [source,text] +---- mvn clean install -Pglv-python mvn deploy -pl gremlin-python -Dpypi +mvn clean install -pl :gremlin-dotnet,:gremlin-dotnet-source -Dnuget +mvn deploy -pl :gremlin-dotnet-source -Dnuget +mvn deploy -pl gremlin-javascript -Dnpm` +---- + +Python, .NET and Javascript do not use the snapshot model the JVM does, however, the build is smart in that it will +dynamically generate a development version number for the GLV artifacts when "-SNAPSHOT" is in the `pom.xml`. + +If you wish to verify that `mvn deploy` works before doing it officially then: -Python does not use the snapshot model the JVM does, however, the build is smart in that it will dynamically -generate a development version number for the Python artifacts when "-SNAPSHOT" is in the `pom.xml`. The previous -command will push the development version to link:https://pypi.python.org/pypi/gremlinpython/[pypi] for distribution. -Use the `testpypi` test environment by updating the `gremlin-python/pom.xml` to verify the `mvn deploy` command works. +* For Python, use the `testpypi` test environment by updating the `gremlin-python/pom.xml`. +* For .NET, use the `staging.nuget.org` environment by updating the `gremlin-dot-source/pom.xml` IMPORTANT: The `clean` in the above commands is more important to the pypi deployment because the process will deploy anything found in the `target/python-packaged/dist` directory. Since the names of the artifacts are based on timestamps, they will not overwrite one another and multiple artifacts will get uploaded. -For .NET and NuGet, development artifacts can be created as follows: - -[source,text] -mvn clean install -pl :gremlin-dotnet,:gremlin-dotnet-source -Dnuget -mvn deploy -pl :gremlin-dotnet-source -Dnuget - -As with PyPi, NuGet does not support a snapshot model as Java does. The commands above will dynamically generate a -version number when "-SNAPSHOT" is in the `pom.xml`. Use the `staging.nuget.org` environment by updating the -`gremlin-dot-source/pom.xml` to ensure the `mvn deploy` command works. - -IMPORTANT: These commands will dynamically edit the `gremlin-dotnet-source/Gremlin.Net.csproj`. Take care to commit -or not commit changes related to that as necessary. +WARNING: These commands will dynamically edit certain files in the various GLVs given automated version number changes. +Take care to commit or not commit changes related to that as necessary. == Release Manager Requirements @@ -235,6 +231,8 @@ for generating javadoc and without that the binary distributions won't contain t .. `mvn deploy -pl gremlin-python -DskipTests -Dpypi` .. `mvn deploy -pl :gremlin-dotnet-source -DskipTests -Dnuget` .. `mvn deploy -pl gremlin-javascript -DskipTests -Dnpm` +. Review the GLV releases at link:https://pypi.org/project/gremlinpython/[PyPi], +link:https://www.nuget.org/packages/Gremlin.Net/[nuget] and link:https://www.npmjs.com/package/gremlin[npm] . `svn co --depth empty https://dist.apache.org/repos/dist/dev/tinkerpop dev; svn up dev/xx.yy.zz` . `svn co --depth empty https://dist.apache.org/repos/dist/release/tinkerpop release; mkdir release/xx.yy.zz` . Copy release files from `dev/xx.yy.zz` to `release/xx.yy.zz`.
