From a83076b7306e2805952324a959528ba6194630fa Mon Sep 17 00:00:00 2001 From: Andres Almiray Date: Tue, 13 Apr 2021 14:53:17 +0200 Subject: [PATCH] Document auto-config releases --- docs/modules/examples/nav.adoc | 1 + .../examples/pages/auto-config-release.adoc | 78 +++++++++++++++++ docs/modules/tools/pages/ant.adoc | 2 +- docs/modules/tools/pages/cli.adoc | 86 ++++++++++++++----- 4 files changed, 146 insertions(+), 21 deletions(-) create mode 100644 docs/modules/examples/pages/auto-config-release.adoc diff --git a/docs/modules/examples/nav.adoc b/docs/modules/examples/nav.adoc index ba25f27..b9d2b74 100644 --- a/docs/modules/examples/nav.adoc +++ b/docs/modules/examples/nav.adoc @@ -1,2 +1,3 @@ .Examples * xref:simple-release.adoc[] +* xref:auto-config-release.adoc[] diff --git a/docs/modules/examples/pages/auto-config-release.adoc b/docs/modules/examples/pages/auto-config-release.adoc new file mode 100644 index 0000000..910d638 --- /dev/null +++ b/docs/modules/examples/pages/auto-config-release.adoc @@ -0,0 +1,78 @@ += AutoConfig Release + +Assuming the project is hosted on GitHub with the "origin" remote set to +pass:[https://github.com/duke/app.git] + +[source,sh] +---- +$ git remote -vvs +origin https://github.com/duke/app.git (fetch) +origin https://github.com/duke/app.git (push) +---- + +And the following file structure: + +[source] +---- +. +├── file1.txt +└── file2.txt +---- + +You may create and tag a release without a config file in the following way: + +[source,sh] +[subs="attributes"] +---- +$ release --auto-config \ + --project-name=app \ + --project-version=1.0.0 \ + --signing-enabled \ + --signing-armored \ + --file=file1.txt \ + --file=file2.txt + +[INFO] JReleaser {jreleaser-version} +[INFO] Auto configure is ON +[INFO] - basedir set to /Home/duke/app +[INFO] - project.name: app +[INFO] - project.version: 1.0.0 +[INFO] - signing.enabled: true +[INFO] - signing.armored: true +[INFO] - file: file1.txt +[INFO] - file: file2.txt +[INFO] Loading properties from /Home/duke/.jreleaser/config.properties +[INFO] Validating configuration +[INFO] Project version set to 1.0.0 +[INFO] Release is not snapshot +[INFO] Timestamp is 2021-04-12T23:28:34.022+02:00 +[INFO] HEAD is at 0357971 +[INFO] dryrun set to false +[INFO] Generating changelog: out/jreleaser/release/CHANGELOG.md +[INFO] Calculating checksums +[INFO] [checksum] file1.txt +[INFO] [checksum] file2.txt +[INFO] Signing files +[INFO] [sign] file1.txt +[INFO] [sign] file2.txt +[INFO] [sign] out/jreleaser/checksums/checksums.txt +[INFO] Releasing to https://github.com/duke/app +[INFO] - uploading file1.txt +[INFO] - uploading file2.txt +[INFO] - uploading checksums.txt +[INFO] - uploading file1.txt.asc +[INFO] - uploading file2.txt.asc +[INFO] - uploading checksums.txt.asc +[INFO] JReleaser succeeded after 1.929s +[INFO] Writing output properties to out/jreleaser/output.properties +---- + +The following environment variables must be provided: + + * `JRELEASER_GITHUB_TOKEN` + * `JRELEASER_GPG_PASSPHRASE` + * `JRELEASER_GPG_PUBLIC_KEY` + * `JRELEASER_GPG_SECRET_KEY` + +Find more information about the options available for this type of releases +xref:tools:cli.adoc#_release[here]. \ No newline at end of file diff --git a/docs/modules/tools/pages/ant.adoc b/docs/modules/tools/pages/ant.adoc index 0ead296..9761eef 100644 --- a/docs/modules/tools/pages/ant.adoc +++ b/docs/modules/tools/pages/ant.adoc @@ -14,7 +14,7 @@ Type:: String Default value:: Property:: jreleaser.format Required:: true -Description:: Configuration file format. Currently supported formats are: `yml`, `json`. +Description:: Configuration file format. Currently supported formats are: `yml`, `toml`, `json`. *overwrite* [horizontal] diff --git a/docs/modules/tools/pages/cli.adoc b/docs/modules/tools/pages/cli.adoc index 637cd08..08d854a 100644 --- a/docs/modules/tools/pages/cli.adoc +++ b/docs/modules/tools/pages/cli.adoc @@ -66,7 +66,7 @@ Display current configuration -w, --warn Set log level to warn. ---- -If `--config-file` is undefined then the command assumes the file is named `jreleaser.[yml|json]` and it's +If `--config-file` is undefined then the command assumes the file is named `jreleaser.[yml|toml|json]` and it's found at the current directory. If `--basedir` is undefined then the command assumes it's the same directory that contains the resolved config file. @@ -124,7 +124,7 @@ Calculate the changelog -w, --warn Set log level to warn. ---- -If `--config-file` is undefined then the command assumes the file is named `jreleaser.[yml|json]` and it's +If `--config-file` is undefined then the command assumes the file is named `jreleaser.[yml|toml|json]` and it's found at the current directory. If `--basedir` is undefined then the command assumes it's the same directory that contains the resolved config file. @@ -147,7 +147,7 @@ Calculate checksums -w, --warn Set log level to warn. ---- -If `--config-file` is undefined then the command assumes the file is named `jreleaser.[yml|json]` and it's +If `--config-file` is undefined then the command assumes the file is named `jreleaser.[yml|toml|json]` and it's found at the current directory. If `--basedir` is undefined then the command assumes it's the same directory that contains the resolved config file. @@ -170,7 +170,7 @@ Sign release artifacts -w, --warn Set log level to warn. ---- -If `--config-file` is undefined then the command assumes the file is named `jreleaser.[yml|json]` and it's +If `--config-file` is undefined then the command assumes the file is named `jreleaser.[yml|toml|json]` and it's found at the current directory. If `--basedir` is undefined then the command assumes it's the same directory that contains the resolved config file. @@ -180,25 +180,71 @@ If `--basedir` is undefined then the command assumes it's the same directory tha [source,bash] ---- jreleaser release -h -Usage: jreleaser release [-dhiqVwy] [-b=] [-c=] +Usage: jreleaser release [-dhiqVwy] [--auto-config] [--overwrite] + [--prerelease] [--signing-armored] [--signing-enabled] + [--skip-tag] [--update] [-b=] + [-c=] [--changelog=] + [--commit-author-email=] + [--commit-author-name=] + [--milestone-name=] + [--project-name=] + [--project-version=] + [--release-name=] [--tag-name=] + [--file=]... Create or update a release - -b, --basedir= Base directory + --auto-config Model auto configuration + -b, --basedir= Base directory -c, --config-file= - The config file - -d, --debug Set log level to debug. - -h, --help Show this help message and exit. - -i, --info Set log level to info. - -q, --quiet Log errors only. - -V, --version Print version information and exit. - -w, --warn Set log level to warn. - -y, --dryrun Skips remote operations. + The config file + --changelog= + Path to changelog file + --commit-author-email= + Commit author e-mail + --commit-author-name= + Commit author name + -d, --debug Set log level to debug. + --file= Input file(s) to be uploaded + -h, --help Show this help message and exit. + -i, --info Set log level to info. + --milestone-name= + The milestone name + --overwrite Overwrite an existing release + --prerelease If the release is a prerelease + --project-name= + The projects name + --project-version= + The projects version + -q, --quiet Log errors only. + --release-name= + The release name + --signing-armored Generate ascii armored signatures + --signing-enabled Sign files + --skip-tag Skip tagging the release + --tag-name= The release tag + --update Update an existing release + -V, --version Print version information and exit. + -w, --warn Set log level to warn. + -y, --dryrun Skips remote operations. ---- -If `--config-file` is undefined then the command assumes the file is named `jreleaser.[yml|json]` and it's +There are two usage modes: + + * auto config + * with explicit configuration file + +*AutoConfig* + +If `--basedir` is undefined then the command assumes it's the same directory where the command is run. + +*Explicit Configuration file* + +If `--config-file` is undefined then the command assumes the file is named `jreleaser.[yml|toml|json]` and it's found at the current directory. If `--basedir` is undefined then the command assumes it's the same directory that contains the resolved config file. +IMPORTANT: None of the command flags that override model properties can be used in this mode. + NOTE: Use `-y` or `--dryrun` during development to verify your configuration settings. No network uploads nor repository mutations should occur when this mode is activated. @@ -225,7 +271,7 @@ Prepare all distributions -w, --warn Set log level to warn. ---- -If `--config-file` is undefined then the command assumes the file is named `jreleaser.[yml|json]` and it's +If `--config-file` is undefined then the command assumes the file is named `jreleaser.[yml|toml|json]` and it's found at the current directory. If `--basedir` is undefined then the command assumes it's the same directory that contains the resolved config file. @@ -284,7 +330,7 @@ Package all distributions -y, --dryrun Skips remote operations. ---- -If `--config-file` is undefined then the command assumes the file is named `jreleaser.[yml|json]` and it's +If `--config-file` is undefined then the command assumes the file is named `jreleaser.[yml|toml|json]` and it's found at the current directory. If `--basedir` is undefined then the command assumes it's the same directory that contains the resolved config file. @@ -346,7 +392,7 @@ Upload all distributions -y, --dryrun Skips remote operations. ---- -If `--config-file` is undefined then the command assumes the file is named `jreleaser.[yml|json]` and it's +If `--config-file` is undefined then the command assumes the file is named `jreleaser.[yml|toml|json]` and it's found at the current directory. If `--basedir` is undefined then the command assumes it's the same directory that contains the resolved config file. @@ -406,7 +452,7 @@ Announce a release -y, --dryrun Skips remote operations. ---- -If `--config-file` is undefined then the command assumes the file is named `jreleaser.[yml|json]` and it's +If `--config-file` is undefined then the command assumes the file is named `jreleaser.[yml|toml|json]` and it's found at the current directory. If `--basedir` is undefined then the command assumes it's the same directory that contains the resolved config file. @@ -449,7 +495,7 @@ Perform a full release -y, --dryrun Skips remote operations. ---- -If `--config-file` is undefined then the command assumes the file is named `jreleaser.[yml|json]` and it's +If `--config-file` is undefined then the command assumes the file is named `jreleaser.[yml|toml|json]` and it's found at the current directory. If `--basedir` is undefined then the command assumes it's the same directory that contains the resolved config file.