rmuir commented on code in PR #16584: URL: https://github.com/apache/lucene/pull/16584#discussion_r3893427502
########## help/publishing.md: ########## @@ -0,0 +1,145 @@ +# Distribution and artifact publishing + +See all distribution-related tasks by running: + +```shell +gradlew tasks --group distribution +``` + +## Maven + +To publish Lucene Maven artifacts to a local `~/.m2` repository, run: + +```shell +gradlew mavenToLocal +``` + +To publish Lucene Maven artifacts to Apache repositories (CI or release manager's job, typically!), run: + +```shell +gradlew mavenToApacheSnapshots -PasfNexusUsername= -PasfNexusPassword= +gradlew mavenToApacheReleases -PasfNexusUsername= -PasfNexusPassword= [optional signing options] +``` + +See artifact signing section below if you plan to use `mavenToApacheReleases`. + +It is a good idea to avoid passing passwords on command line. CI jobs have these properties saved in +`~/.gradle/gradle.properties` - this way they are read automatically. + +Apache Releases repository will not accept snapshots. + +## Release (distribution) artifacts + +To collect all release artifacts, and optionally sign them, run: + +```shell +gradlew assembleRelease [optional signing options] +``` + +All distribution artifacts will be placed under: + +```text +lucene/distribution/build/release +``` + +Artifact signing is optional (but required if you're really making a release). + +## Artifact signing + +Certain tasks may optionally sign artifacts or require artifacts to be signed: + +- `assembleRelease` +- `mavenToApacheReleases` + +Signing can be enabled by adding the `-Psign` option, for example: + +```shell +gradlew assembleRelease mavenToApacheReleases -Psign +``` + +By default, gradle uses a Java-based implementation of PGP for signing, which requires several `signing.*` properties +via either `~/.gradle/gradle.properties` or command-line options: + +<https://docs.gradle.org/current/userguide/signing_plugin.html#sec:signatory_credentials> + +An example full command-line that assembles signed artifacts could look like this: + +```shell +gradlew assembleRelease mavenToApacheReleases -Psign -Psigning.keyId=... -Psigning.password=... -Psigning.secretKeyRingFile=... +``` + +The keyId is the last 8 digits of your key (`gpg -k` will print your keys). Gradle documentation has more options of +secure passing of private key information and passwords. + +## Artifact signing using an external GPG with GPG Agent + +You can use an external GPG command to deal with signing artifacts, without needing to give gradle your passphrase, by +adding a `-PuseGpg=true` option, but this changes the properties you must specify: + +For gpg2: + +```shell +gradlew [tasks] -Psign -PuseGpg=true -Psigning.gnupg.keyName=... +``` + +For gpg: + +```shell +gradlew [tasks] -Psign -PuseGpg=true -Psigning.gnupg.keyName=... -Psigning.gnupg.useLegacyGpg=true +``` + +The keyName is the last 8 digits of your key (`gpg -k` will print your keys). + +There are additional (optional) `signing.gnupg.*` properties which exist that may be useful/necessary in your system: + +```properties +signing.gnupg.useLegacyGpg=true # Changes the default executable from `gpg2` to `gpg` and explicitly sets `--use-agent` +signing.gnupg.executable=gpg # Allows explicit control over what command executable used (ex: `gpg2`, `gpg`, `gpg.exe`, etc...) +signing.gnupg.homeDir=/tmp/gnupg-home # overrides GnuPG's default home directory (ex: `~/.gnupg/`) +signing.gnupg.optionsFile=/tmp/gnupg-home/my.conf # overrides GnuPG's default configuration file +signing.gnupg.passphrase=... # Provide your passphrase to gradle to hand off to gpg. *NOT RECOMMENDED*, see below. +``` Review Comment: Java Properties files don't support trailing comments, this sometimes gets highlighted incorrectly. we should move these to line comments above each thing they are documenting. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
