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

A Maven project with existing releases may prove troublesome without
setting the tag value.

README.md

@@ -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>