You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@maven.apache.org by GitBox <gi...@apache.org> on 2022/09/09 12:05:33 UTC
[GitHub] [maven-site] gnodet commented on a diff in pull request #287: [MNGSITE-492] Maven Repositories documentation
gnodet commented on code in PR #287:
URL: https://github.com/apache/maven-site/pull/287#discussion_r966993926
##########
content/markdown/repositories/artifacts.md:
##########
@@ -0,0 +1,122 @@
+# Maven Artifacts
+
+<!--
+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.
+-->
+
+Artifact is "anything" that Maven downloads, installs or deploys for you. Most of them are POMs and JARs but
+the artifact can be really anything. A very important thing about artifacts is that they have coordinates,
+so they are not "just files", but they are files that are in some way addressable by Maven.
+
+Artifact coordinates, are most often represented as `groupId:artifactId:version`, or GAV in short or when
+informally used (please note that Artifact coordinates has more fields, but for brevity we still call the
+coordinates "GAV", not "GAVCE"). The artifact coordinate uniquely describe the artifact you are referring to,
+but does not tell anything about its source (or origin). It is up to Maven to figure out (or you to tell Maven
+how to figure it out).
+
+While Maven internally uses notion of "artifact" thoroughly (just look at sources!), end user may never hit this name.
+That's due the fact, that while for Maven, "everything is artifact" (internally), Maven end users actually speak about
+"projects", "parent projects", "dependencies", "build plugins", "build extensions" and so on.
+
+## Artifact properties
+
+The artifacts that Maven (internally) uses has following (for our topic related) properties:
+
+| Name | Description |
+|------------|---------------------------------------------------|
+| groupId | The artifact group |
+| artifactId | The artifact name |
+| version | The artifact version |
+| classifier | The artifact distinguishing classifier (optional) |
+| extension | The artifact extension |
+
+Some more properties worth mention, is a bit of special one: `baseVersion` that is actually derived from version
+(or other way around, depends on context): for release artifacts holds same value as `version`, for snapshot artifacts
+holds "non-timestamped snapshot version". For example, for snapshot `version` "1.0-20220119.164608-1" value of the
+`baseVersion` would have value "1.0-SNAPSHOT". So, `version` and `baseVersion` are linked, derived from each other,
+but they have different values only in case of snapshots.
+
+## But where do I set Artifact extension?
+
+In short, nowhere. Or maybe "you rarely have to". Maven POM (where you declare your project, parent project,
+dependencies, plugins and other), maps those elements onto artifact coordinates with some extra logic. In case
+of "project" and "parent project" aka POMs:
+
+| Project | Artifact |
+|------------|---------------|
+| groupId | -> groupId |
+| artifactId | -> artifactId |
+| version | -> version |
+| classifier | -> |
+| extension | -> `pom` |
+
+In case of "build plugins" and "build extensions", as they are JARs, this is how corresponding elements are mapped:
+
+| Plugin | Artifact |
+|------------|---------------|
+| groupId | -> groupId |
+| artifactId | -> artifactId |
+| version | -> version |
+| classifier | -> |
+| extension | -> `jar` |
+
+And finally, in case of "dependencies", this is the mapping (no, scope is NOT part of artifact coordinates, is used in
+dependency resolution only):
+
+| Dependency | Artifact |
+|------------|-------------------------------------------|
+| groupId | -> groupId |
+| artifactId | -> artifactId |
+| version | -> version |
+| classifier | -> classifier |
+| type | -> type handler provided, or same as type |
+
+Here, we need to make a short detour to explain "type" (of a dependency) and how it becomes artifact extension.
+
+Maven for dependencies defines "type", that describes what that dependency is (should it be added to classpath and
+many other things). Plugins and extensions may define new types, that is usually a must for plugins introducing
+a "packaging" (lifecycle mapping) by providing ArtifactHandlers components with name corresponding to type name.
+
+Maven Core out of the box defines following "types" (ArtifactHandlers):
Review Comment:
> Maven Core out of the box defines following "types" (handled by `ArtifactHandler` instances):
##########
content/markdown/repositories/artifacts.md:
##########
@@ -0,0 +1,122 @@
+# Maven Artifacts
+
+<!--
+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.
+-->
+
+Artifact is "anything" that Maven downloads, installs or deploys for you. Most of them are POMs and JARs but
Review Comment:
> An artifact is "anything"
##########
content/markdown/repositories/artifacts.md:
##########
@@ -0,0 +1,122 @@
+# Maven Artifacts
+
+<!--
+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.
+-->
+
+Artifact is "anything" that Maven downloads, installs or deploys for you. Most of them are POMs and JARs but
+the artifact can be really anything. A very important thing about artifacts is that they have coordinates,
+so they are not "just files", but they are files that are in some way addressable by Maven.
+
+Artifact coordinates, are most often represented as `groupId:artifactId:version`, or GAV in short or when
+informally used (please note that Artifact coordinates has more fields, but for brevity we still call the
+coordinates "GAV", not "GAVCE"). The artifact coordinate uniquely describe the artifact you are referring to,
+but does not tell anything about its source (or origin). It is up to Maven to figure out (or you to tell Maven
+how to figure it out).
+
+While Maven internally uses notion of "artifact" thoroughly (just look at sources!), end user may never hit this name.
+That's due the fact, that while for Maven, "everything is artifact" (internally), Maven end users actually speak about
+"projects", "parent projects", "dependencies", "build plugins", "build extensions" and so on.
+
+## Artifact properties
+
+The artifacts that Maven (internally) uses has following (for our topic related) properties:
+
+| Name | Description |
+|------------|---------------------------------------------------|
+| groupId | The artifact group |
+| artifactId | The artifact name |
+| version | The artifact version |
+| classifier | The artifact distinguishing classifier (optional) |
+| extension | The artifact extension |
+
+Some more properties worth mention, is a bit of special one: `baseVersion` that is actually derived from version
+(or other way around, depends on context): for release artifacts holds same value as `version`, for snapshot artifacts
+holds "non-timestamped snapshot version". For example, for snapshot `version` "1.0-20220119.164608-1" value of the
+`baseVersion` would have value "1.0-SNAPSHOT". So, `version` and `baseVersion` are linked, derived from each other,
+but they have different values only in case of snapshots.
+
+## But where do I set Artifact extension?
+
+In short, nowhere. Or maybe "you rarely have to". Maven POM (where you declare your project, parent project,
+dependencies, plugins and other), maps those elements onto artifact coordinates with some extra logic. In case
+of "project" and "parent project" aka POMs:
+
+| Project | Artifact |
+|------------|---------------|
+| groupId | -> groupId |
+| artifactId | -> artifactId |
+| version | -> version |
+| classifier | -> |
+| extension | -> `pom` |
+
+In case of "build plugins" and "build extensions", as they are JARs, this is how corresponding elements are mapped:
+
+| Plugin | Artifact |
+|------------|---------------|
+| groupId | -> groupId |
+| artifactId | -> artifactId |
+| version | -> version |
+| classifier | -> |
+| extension | -> `jar` |
+
+And finally, in case of "dependencies", this is the mapping (no, scope is NOT part of artifact coordinates, is used in
+dependency resolution only):
+
+| Dependency | Artifact |
+|------------|-------------------------------------------|
+| groupId | -> groupId |
+| artifactId | -> artifactId |
+| version | -> version |
+| classifier | -> classifier |
+| type | -> type handler provided, or same as type |
+
+Here, we need to make a short detour to explain "type" (of a dependency) and how it becomes artifact extension.
+
+Maven for dependencies defines "type", that describes what that dependency is (should it be added to classpath and
+many other things). Plugins and extensions may define new types, that is usually a must for plugins introducing
+a "packaging" (lifecycle mapping) by providing ArtifactHandlers components with name corresponding to type name.
+
+Maven Core out of the box defines following "types" (ArtifactHandlers):
+
+| Name | Extension | Classifier |
+|--------------|-----------|--------------|
+| pom | `pom` | |
+| jar | `jar` | |
+| maven-plugin | `jar` | |
+| ear | `ear` | |
+| ejb | `jar` | |
+| ejb-client | `jar` | `ejb-client` |
+| javadoc | `jar` | `javadoc` |
+| java-source | `jar` | `sources` |
+| rar | `rar` | |
+| test-jar | `jar` | `tests` |
+| war | `war` | |
+| **any** | any | |
+
+So, from table above, we can see that if we define dependency type as "war", we will hit the "war" handler, that will
+result in the `war` extension (may not be obvious, as type and extension we end up is same, but internally this
Review Comment:
> result in using the `war` extension (which may not be obvious as the type and extension we end up with are the same, but internally this
##########
content/markdown/repositories/artifacts.md:
##########
@@ -0,0 +1,122 @@
+# Maven Artifacts
+
+<!--
+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.
+-->
+
+Artifact is "anything" that Maven downloads, installs or deploys for you. Most of them are POMs and JARs but
+the artifact can be really anything. A very important thing about artifacts is that they have coordinates,
+so they are not "just files", but they are files that are in some way addressable by Maven.
+
+Artifact coordinates, are most often represented as `groupId:artifactId:version`, or GAV in short or when
+informally used (please note that Artifact coordinates has more fields, but for brevity we still call the
+coordinates "GAV", not "GAVCE"). The artifact coordinate uniquely describe the artifact you are referring to,
+but does not tell anything about its source (or origin). It is up to Maven to figure out (or you to tell Maven
+how to figure it out).
+
+While Maven internally uses notion of "artifact" thoroughly (just look at sources!), end user may never hit this name.
+That's due the fact, that while for Maven, "everything is artifact" (internally), Maven end users actually speak about
+"projects", "parent projects", "dependencies", "build plugins", "build extensions" and so on.
+
+## Artifact properties
+
+The artifacts that Maven (internally) uses has following (for our topic related) properties:
+
+| Name | Description |
+|------------|---------------------------------------------------|
+| groupId | The artifact group |
+| artifactId | The artifact name |
+| version | The artifact version |
+| classifier | The artifact distinguishing classifier (optional) |
+| extension | The artifact extension |
+
+Some more properties worth mention, is a bit of special one: `baseVersion` that is actually derived from version
+(or other way around, depends on context): for release artifacts holds same value as `version`, for snapshot artifacts
+holds "non-timestamped snapshot version". For example, for snapshot `version` "1.0-20220119.164608-1" value of the
+`baseVersion` would have value "1.0-SNAPSHOT". So, `version` and `baseVersion` are linked, derived from each other,
+but they have different values only in case of snapshots.
+
+## But where do I set Artifact extension?
+
+In short, nowhere. Or maybe "you rarely have to". Maven POM (where you declare your project, parent project,
+dependencies, plugins and other), maps those elements onto artifact coordinates with some extra logic. In case
+of "project" and "parent project" aka POMs:
+
+| Project | Artifact |
+|------------|---------------|
+| groupId | -> groupId |
+| artifactId | -> artifactId |
+| version | -> version |
+| classifier | -> |
+| extension | -> `pom` |
+
+In case of "build plugins" and "build extensions", as they are JARs, this is how corresponding elements are mapped:
+
+| Plugin | Artifact |
+|------------|---------------|
+| groupId | -> groupId |
+| artifactId | -> artifactId |
+| version | -> version |
+| classifier | -> |
+| extension | -> `jar` |
+
+And finally, in case of "dependencies", this is the mapping (no, scope is NOT part of artifact coordinates, is used in
+dependency resolution only):
+
+| Dependency | Artifact |
+|------------|-------------------------------------------|
+| groupId | -> groupId |
+| artifactId | -> artifactId |
+| version | -> version |
+| classifier | -> classifier |
+| type | -> type handler provided, or same as type |
+
+Here, we need to make a short detour to explain "type" (of a dependency) and how it becomes artifact extension.
+
+Maven for dependencies defines "type", that describes what that dependency is (should it be added to classpath and
+many other things). Plugins and extensions may define new types, that is usually a must for plugins introducing
+a "packaging" (lifecycle mapping) by providing ArtifactHandlers components with name corresponding to type name.
+
+Maven Core out of the box defines following "types" (ArtifactHandlers):
+
+| Name | Extension | Classifier |
+|--------------|-----------|--------------|
+| pom | `pom` | |
+| jar | `jar` | |
+| maven-plugin | `jar` | |
+| ear | `ear` | |
+| ejb | `jar` | |
+| ejb-client | `jar` | `ejb-client` |
+| javadoc | `jar` | `javadoc` |
+| java-source | `jar` | `sources` |
+| rar | `rar` | |
+| test-jar | `jar` | `tests` |
+| war | `war` | |
+| **any** | any | |
+
+So, from table above, we can see that if we define dependency type as "war", we will hit the "war" handler, that will
+result in the `war` extension (may not be obvious, as type and extension we end up is same, but internally this
+indirection does happen). More obvious is type "test-jar", where we end up with extension `jar`. Finally, the **any**
Review Comment:
> The "test-jar" is more obvious and it translates to the `jar` extension.
##########
content/markdown/repositories/artifacts.md:
##########
@@ -0,0 +1,122 @@
+# Maven Artifacts
+
+<!--
+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.
+-->
+
+Artifact is "anything" that Maven downloads, installs or deploys for you. Most of them are POMs and JARs but
+the artifact can be really anything. A very important thing about artifacts is that they have coordinates,
+so they are not "just files", but they are files that are in some way addressable by Maven.
+
+Artifact coordinates, are most often represented as `groupId:artifactId:version`, or GAV in short or when
+informally used (please note that Artifact coordinates has more fields, but for brevity we still call the
+coordinates "GAV", not "GAVCE"). The artifact coordinate uniquely describe the artifact you are referring to,
+but does not tell anything about its source (or origin). It is up to Maven to figure out (or you to tell Maven
+how to figure it out).
+
+While Maven internally uses notion of "artifact" thoroughly (just look at sources!), end user may never hit this name.
+That's due the fact, that while for Maven, "everything is artifact" (internally), Maven end users actually speak about
+"projects", "parent projects", "dependencies", "build plugins", "build extensions" and so on.
+
+## Artifact properties
+
+The artifacts that Maven (internally) uses has following (for our topic related) properties:
+
+| Name | Description |
+|------------|---------------------------------------------------|
+| groupId | The artifact group |
+| artifactId | The artifact name |
+| version | The artifact version |
+| classifier | The artifact distinguishing classifier (optional) |
+| extension | The artifact extension |
+
+Some more properties worth mention, is a bit of special one: `baseVersion` that is actually derived from version
+(or other way around, depends on context): for release artifacts holds same value as `version`, for snapshot artifacts
+holds "non-timestamped snapshot version". For example, for snapshot `version` "1.0-20220119.164608-1" value of the
+`baseVersion` would have value "1.0-SNAPSHOT". So, `version` and `baseVersion` are linked, derived from each other,
+but they have different values only in case of snapshots.
+
+## But where do I set Artifact extension?
+
+In short, nowhere. Or maybe "you rarely have to". Maven POM (where you declare your project, parent project,
+dependencies, plugins and other), maps those elements onto artifact coordinates with some extra logic. In case
+of "project" and "parent project" aka POMs:
+
+| Project | Artifact |
+|------------|---------------|
+| groupId | -> groupId |
+| artifactId | -> artifactId |
+| version | -> version |
+| classifier | -> |
+| extension | -> `pom` |
+
+In case of "build plugins" and "build extensions", as they are JARs, this is how corresponding elements are mapped:
+
+| Plugin | Artifact |
+|------------|---------------|
+| groupId | -> groupId |
+| artifactId | -> artifactId |
+| version | -> version |
+| classifier | -> |
+| extension | -> `jar` |
+
+And finally, in case of "dependencies", this is the mapping (no, scope is NOT part of artifact coordinates, is used in
+dependency resolution only):
+
+| Dependency | Artifact |
+|------------|-------------------------------------------|
+| groupId | -> groupId |
+| artifactId | -> artifactId |
+| version | -> version |
+| classifier | -> classifier |
+| type | -> type handler provided, or same as type |
+
+Here, we need to make a short detour to explain "type" (of a dependency) and how it becomes artifact extension.
+
+Maven for dependencies defines "type", that describes what that dependency is (should it be added to classpath and
+many other things). Plugins and extensions may define new types, that is usually a must for plugins introducing
+a "packaging" (lifecycle mapping) by providing ArtifactHandlers components with name corresponding to type name.
+
+Maven Core out of the box defines following "types" (ArtifactHandlers):
+
+| Name | Extension | Classifier |
+|--------------|-----------|--------------|
+| pom | `pom` | |
+| jar | `jar` | |
+| maven-plugin | `jar` | |
+| ear | `ear` | |
+| ejb | `jar` | |
+| ejb-client | `jar` | `ejb-client` |
+| javadoc | `jar` | `javadoc` |
+| java-source | `jar` | `sources` |
+| rar | `rar` | |
+| test-jar | `jar` | `tests` |
+| war | `war` | |
+| **any** | any | |
+
+So, from table above, we can see that if we define dependency type as "war", we will hit the "war" handler, that will
Review Comment:
> we define the dependency type
##########
content/markdown/repositories/artifacts.md:
##########
@@ -0,0 +1,122 @@
+# Maven Artifacts
+
+<!--
+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.
+-->
+
+Artifact is "anything" that Maven downloads, installs or deploys for you. Most of them are POMs and JARs but
+the artifact can be really anything. A very important thing about artifacts is that they have coordinates,
Review Comment:
the -> an
> an artifact can be
--
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: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org