This is an automated email from the ASF dual-hosted git repository.
elharo pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-site.git
The following commit(s) were added to refs/heads/master by this push:
new 21821f3b [MNGSITE-368] Rephrase naming conventions (#642)
21821f3b is described below
commit 21821f3b37a0381394e5b3ad3f66e63b1626c640
Author: Matthias Bünger <[email protected]>
AuthorDate: Sun Jan 19 22:29:55 2025 +0100
[MNGSITE-368] Rephrase naming conventions (#642)
* MNGSITE-368 Rephrase naming conventions
---
.../apt/guides/mini/guide-naming-conventions.apt | 63 ----------
.../guides/mini/guide-naming-conventions.md | 128 +++++++++++++++++++++
2 files changed, 128 insertions(+), 63 deletions(-)
diff --git a/content/apt/guides/mini/guide-naming-conventions.apt
b/content/apt/guides/mini/guide-naming-conventions.apt
deleted file mode 100644
index 1b6470b2..00000000
--- a/content/apt/guides/mini/guide-naming-conventions.apt
+++ /dev/null
@@ -1,63 +0,0 @@
- ------
- Guide to Naming Conventions
- ------
- Carlos Sanchez
- ------
- 2005-11-01
- ------
-
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
-
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
-
-Guide to naming conventions on groupId, artifactId, and version
-
- []
-
- * <<groupId>> uniquely identifies your project across all projects.
- A group ID should follow
{{{https://docs.oracle.com/javase/specs/jls/se6/html/packages.html#7.7}Java's
- package name rules}}. This means it starts with a reversed domain name you
control.
- For example,
-
- <<<org.apache.maven>>>, <<<org.apache.commons>>>
-
- Maven does not enforce this rule. There are many legacy projects that do not
follow
- this convention and instead use single word group IDs. However, it will be
difficult
- to get a new single word group ID approved for inclusion in the Maven Central
repository.
-
- You can create as many subgroups as you want.
- A good way to determine the granularity of the <<<groupId>>> is to use the
project structure. That is, if
- the current project is a multiple module project, it should append a new
identifier to the parent's
- <<<groupId>>>. For example,
-
- <<<org.apache.maven>>>, <<<org.apache.maven.plugins>>>,
<<<org.apache.maven.reporting>>>
-
- * <<artifactId>> is the name of the jar without version. If you created it,
then you can choose
- whatever name you want with lowercase letters and no strange symbols. If it's
a third party jar,
- you have to take the name of the jar as it's distributed.
-
- eg. <<<maven>>>, <<<commons-math>>>
-
- * <<version>> if you distribute it, then you can choose any typical version
with numbers and dots
- (1.0, 1.1, 1.0.1, ...).
- Don't use dates as they are usually associated with SNAPSHOT (nightly)
builds. If it's a third
- party artifact, you have to use their version number whatever it is, and as
strange as it can look.
- For example,
-
- <<<2.0>>>, <<<2.0.1>>>, <<<1.3.1>>>
diff --git a/content/markdown/guides/mini/guide-naming-conventions.md
b/content/markdown/guides/mini/guide-naming-conventions.md
new file mode 100644
index 00000000..67330d90
--- /dev/null
+++ b/content/markdown/guides/mini/guide-naming-conventions.md
@@ -0,0 +1,128 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>Naming conventions of Maven coordinates (groupId, artifactId, and
version)</title>
+</head>
+
+# Naming convention of Maven coordinates
+
+So that Maven can identify and utilise any artifact (e.g. a `.jar` file),
every artifact must be identifiable through a
+unique combination of three identifiers.
+This combination is called the "[Maven coordinates][4]".
+Maven coordinates consist of a project group identifier named `groupId`, an
artifact identifier named `artifactId`, and
+the version identifier named `version`.
+
+This document defines the naming conventions of Maven coordinates.
+
+You should follow this convention whenever you create a new artifact.
+
+## Project group identifier
+
+When projects of the same organization are topically related, we say they
belong to the same "project group".
+The `groupId` uniquely identifies a project group across all other groups.
+Each `groupId` should follow [Java's package name rules][1].
+This means it starts with a reversed domain name you control.
+
+Examples
+
+```
+org.apache.maven
+org.apache.commons
+com.google.guava
+```
+
+There are many legacy projects that do not follow this convention and instead
use single word group IDs.
+However, it will be difficult to get a new single word group ID approved for
inclusion in the Maven Central repository.
+
+You can create as many subgroups as you want.
+A good way to determine the granularity of the `groupId` is to look at the
project group's structure.
+If there are multiple projects of the same topic or type, e.g. plugins, those
may be grouped in a subgroup.
+Each subgroup should append a new identifier to the parent's `groupId`.
+
+Example
+
+```
+// Parent project group
+org.apache.maven
+
+// Subgroups
+org.apache.maven.plugins
+org.apache.maven.reporting
+```
+
+## Artifact identifier
+
+The `artifactId` is the name of the artifact.
+The identifiers should only consist of *lowercase* letters, digits, and
hyphens.
+
+Examples
+
+```
+commons-math
+maven-clean-plugin
+```
+
+## Version identifier
+
+We recommend that the `version` follow the rules of [Semantic Versioning
1.0.0][2].
+It should start with the major version, followed by the minor version and the
patch version.
+All three are numeric, separated by a dot.
+
+Examples
+
+```
+1.0.0
+2.3.2
+3.5.42
+```
+
+You can add labels for pre-releases or build metadata after the patch version.
+Avoid using dates in those labels, because they are usually associated with
unstable versions.
+
+Examples
+
+```
+// Pre-releases
+1.0.0-beta
+1.0.0-M1
+1.0.0-rc2
+
+// Build metadata
+1.2.3+dfc0c87
+2.3.4+15433
+```
+
+### Unstable versions (SNAPSHOT)
+
+`SNAPSHOT`s are artifacts built in between releases.
+They may be built from a particular commit or from code that isn't even
committed to the source repository.
+They are a snapshot of the project at a particular point in time, generally
used for testing.
+Unlike release versions, snapshot artifacts can and do change over time.
+
+Usually the snapshot has the version of the next anticipated release followed
by `-SNAPSHOT`, e.g. `1.0.1-SNAPSHOT`.
+
+Maven treats artifacts with such versions in a special way during deployment
and stores them in the `snapshotRepository`
+if one is defined in the [POM file][3].
+
+[1]:https://docs.oracle.com/javase/specs/jls/se21/html/jls-6.html#d5e8762
+[2]:https://semver.org/spec/v1.0.0.html
+[3]:/pom.html#Repository
+[4]:/pom.html#Maven_Coordinates
+
