Skip to content
Snippets Groups Projects
Commit 02e1f8ff authored by Pierre Smeyers's avatar Pierre Smeyers
Browse files

Merge branch 'maven-semrel-fixup' into 'master' 

chore(doc): Clarify the use of semrel in maven

Closes #24

See merge request to-be-continuous/maven!32
parents b1e09ca0 e0339a91
Branches
Tags
No related merge requests found
Show whitespace changes
Inline Side-by-side
Showing
with 27 additions and 23 deletions
README.md
+ 27
− 23
View file @ 02e1f8ff
......@@ -17,7 +17,7 @@ include:
## Global configuration
The Maven template uses some global configuration used throughout all jobs.
The Maven template uses some global configuration throughout all jobs.
| Name | description | default value |
| --------------------- | -------------------------------------- | ----------------- |
......@@ -29,7 +29,7 @@ The Maven template uses some global configuration used throughout all jobs.
### About `$MAVEN_CFG_DIR`
This variable is used to define the Maven configuration directory. It is used for 2 purposes:
This variable is used to define the Maven configuration directory. It is used for two (2) purposes:
* in case a Maven settings file (`settings.xml`) is found, the template automatically uses it (using the `-s` option on command line),
* the cache policy declares the `${MAVEN_CFG_DIR}/repository` directory as cached (not to download Maven dependencies over and over again).
......@@ -63,9 +63,9 @@ If yo want to fix the JaCoCo plugin version or tweak the default configuration,
[JaCoCo Maven Plugin](https://www.eclemma.org/jacoco/trunk/doc/maven.html) in your `pom.xml`, but be aware of the
following:
* do not declare JaCoCo executions for `prepare-agent` and `report` goals otherwise then would be ran twice during
* do not declare JaCoCo executions for `prepare-agent` and `report` goals as each would run twice during
unit tests (not necessarily with the expected configuration). If you really need to do so anyway, you'll have to
override the `$MAVEN_BUILD_ARGS` variable to remove explicit invocation to JaCoCo goals.
override the `$MAVEN_BUILD_ARGS` variable to remove the explicit invocation to JaCoCo goals.
* make sure the `report` goal computes a CSV report, that is used by the Maven template to compute the global coverage stat.
More info:
......@@ -128,7 +128,7 @@ More info:
### `mvn-forbid-snapshot-dependencies` job
This job checks your project has release-only dependencies (no _snapshot_), using the [Maven Enforcer](https://maven.apache.org/enforcer/enforcer-rules/requireReleaseDeps.html) plugin.
This job checks if the project has release-only dependencies, i.e., no `_*-SNAPSHOT_` versions, using the [Maven Enforcer](https://maven.apache.org/enforcer/enforcer-rules/requireReleaseDeps.html) plugin.
Failure is allowed in feature branches.
......@@ -140,9 +140,9 @@ It is bound to the `test` stage, and uses the following variables:
### `mvn-snapshot` & `mvn-release` jobs
Those jobs are **disabled by default** and perform respectively:
These jobs are **disabled by default** and perform, respectively, the following:
* a [Maven deploy](https://maven.apache.org/plugins/maven-deploy-plugin/) of your Java packages (jar, war or else),
* a [Maven deploy](https://maven.apache.org/plugins/maven-deploy-plugin/) of your Java packages (jar, war, etc.),
* a [Maven release](http://maven.apache.org/maven-release/maven-release-plugin/index.html) of your current branch.
They are bound to the `publish` stage, and use the following variables:
......@@ -165,21 +165,26 @@ More info:
If you activate the [`semantic-release-info` job from the `semantic-release` template](https://gitlab.com/to-be-continuous/semantic-release/#semantic-release-info-job), the `mvn-release` job will rely on the generated next version info.
* the release will only be performed if a next semantic release is present
* the version is passed to the maven release plugin as release version argument adding `-DreleaseVersion=${SEMREL_INFO_NEXT_VERSION}` to the `MAVEN_RELEASE_ARGS` value
* the release will only be performed if a semantic release is present
* the version is passed to the Maven Release plugin as the release version argument adding `-DreleaseVersion=${SEMREL_INFO_NEXT_VERSION}` to the `MAVEN_RELEASE_ARGS` value
:warning: Both maven release plugin and semantic-release use a dedicated tag format that need to be set accordingly.
By default maven release plugin uses `${artifactId}-${version}` and semantic-release uses `s${version}`
:warning: Both the Maven Release plugin and semantic-release template use a dedicated tag format that need to be set accordingly.
By default, the Maven Release plugin uses `${artifactId}-${version}` and semantic-release uses `${version}`
For exemple you can modify the semantic-release tag format with the `SEMREL_TAG_FORMAT` variable (see [semantic-release template variables](https://gitlab.com/to-be-continuous/semantic-release/#variables)).
:information_source: semantic-release determines the next release version from the existing tags in the Git repository. As the default semantic-release tag format (`${version}`) is _not_ the Maven default, if leaving defaults, semantic-release will always determine the next version to release as `1.0.0`, trying to keep overwriting the same version.
In addition to the functional problem, this might result in a release failure as soon as trying to release version `1.0.0` for the second time (as Maven repos configured as "release" repos will not permit overwriting).
Simply set `SEMREL_TAG_FORMAT` as shown below to have the semantic-release tag format match the maven release plugin one.
```yml
variables:
# double dollar to prevent evaluation (escape char)
SEMREL_TAG_FORMAT: "myArtifactId-$${version}"
```
Or you can [override the maven release plugin tag format](http://maven.apache.org/maven-release/maven-release-plugin/examples/prepare-release.html#Overriding_the_default_tag_name_format).
Note: You can disable the `semantic-release` job (as it's the `mvn-release` job that will perform the release and so we only need the `semantic-release-info` job) with the `SEMREL_RELEASE_DISABLED` variable.
Note: It is the `mvn-release` job that will perform the release and so you only need the `semantic-release-info` job. Set the `SEMREL_RELEASE_DISABLED` variable as shown below.
```yml
variables:
......@@ -192,14 +197,13 @@ Finally, the semantic-release integration can be disabled with the `MVN_SEMREL_R
Your Maven repository may require authentication credentials to publish artifacts.
You shall handle them in the following way:
You may handle them in the following ways:
1. define all required credentials as :lock: [project variables](https://docs.gitlab.com/ee/ci/variables/#create-a-custom-variable-in-the-ui),
2. make sure your `pom.xml` (or ancestor) [declares your `<repository>` and `<snapshotRepository>` with server **id**s in a `<distributionManagement>` section](https://maven.apache.org/pom.html#repository),
3. in your `${MAVEN_CFG_DIR}/settings.xml` file, [define the repository servers credentials in the `<servers>` section](https://maven.apache.org/settings.html#Servers)
using the `${env.VARIABLE}` pattern (will be automatically evaluated and replaced by Maven).
3. in your `${MAVEN_CFG_DIR}/settings.xml` file, [define the repository servers credentials in the `<servers>` section](https://maven.apache.org/settings.html#Servers) using the `${env.VARIABLE}` pattern—will be automatically evaluated and replaced by Maven.
**Example 1** (using the [GitLab Maven Repository](https://docs.gitlab.com/ee/user/packages/maven_repository/)):
**Example 1** — using the [GitLab Maven Repository](https://docs.gitlab.com/ee/user/packages/maven_repository/)
`pom.xml`:
......@@ -240,7 +244,7 @@ You shall handle them in the following way:
</settings>
```
**Example 2** (using an Artifactory repository with same credentials for snapshot &amp; release):
**Example 2** — using an Artifactory repository with same credentials for snapshot &amp; release
`pom.xml`:
......@@ -285,9 +289,9 @@ You shall handle them in the following way:
A Maven release involves some Git push operations.
You can either use a ssh key or an authenticated and authorized Git user.
You can either use an `ssh` key or an authenticated and authorized Git user.
##### Using a SSH key
##### Using an SSH key
We recommend you to use a [project deploy key](https://docs.gitlab.com/ee/user/project/deploy_keys/#project-deploy-keys) with write access to your project.
......@@ -301,9 +305,9 @@ blablabla
-----END OPENSSH PRIVATE KEY-----
```
The template handle both classic variable and file variable.
The template handles both classic variable and file variable.
:warning: The scm connections in your pom.xml should use the ssh protocol
:warning: The `scm` connections in your `pom.xml` should use the `ssh` protocol
```xml
<scm>
......@@ -315,12 +319,12 @@ The template handle both classic variable and file variable.
##### Using Git user authentication
Simply specify :lock: `$GIT_USERNAME` and :lock: `$GIT_PASSWORD` as protected project variables : they will be dynamically
Simply specify :lock: `$GIT_USERNAME` and :lock: `$GIT_PASSWORD` as protected project variables and they will be dynamically
evaluated and appended to the Maven release arguments.
Note that the password should be an access token with `read_repository` and `write_repository` scopes.
:warning: The scm connections in your pom.xml should use the https protocol
:warning: The `scm` connections in your `pom.xml` should use the `https` protocol
```xml
<scm>
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment