elharo commented on code in PR #629: URL: https://github.com/apache/maven-site/pull/629#discussion_r1941968460
########## content/markdown/repositories/artifacts.md: ########## @@ -98,13 +91,14 @@ And finally, in case of "dependencies", this is the mapping (no, scope is NOT pa | classifier | `project/dependencies/dependency[x]/classifier` | -> classifier | | extension | `project/dependencies/dependency[x]/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. +Here, we need to make a short detour to explain "dependency type" and how it becomes an 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 `ArtifactHandler` components with name corresponding to type name. +A dependency type determines how the artifact referenced by the dependency is used. +For example, should it be added to comple-time classpath, the test classpath, or both? +Plugins and extensions may define new types. This is usually required for plugins introducing +a "packaging" (lifecycle mapping) by providing `ArtifactHandler` components with a name corresponding to type name. -Maven Core out of the box [defines following "types" (handled by same named `ArtifactHandler` components)](/ref/current/maven-core/artifact-handlers.html): +Out of the box, Maven Core defines the [following "types" (handled by the same named `ArtifactHandler` components)](/ref/current/maven-core/artifact-handlers.html): | Type Name | Extension | Classifier | |--------------|-----------|--------------| Review Comment: Maven 4 hasn't shipped yet ########## content/markdown/repositories/artifacts.md: ########## @@ -19,55 +19,48 @@ specific language governing permissions and limitations under the License. --> -An Artifact is "anything" (any file) that can be addressed using its coordinates, and Maven downloads, installs or -deploys for you. Most of them are POMs and JARs but -an artifact can be really anything. A very important thing about artifacts is that they have coordinates, +An artifact is a file (more precisely, a sequence of bytes) that can be addressed using its coordinates +and which Maven downloads, installs, or deploys for you. Most artifacts are POMs and JARs, but +an artifact can be really any file. 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 coordinates 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). +Artifact coordinates are most often represented as `groupId:artifactId:version`, or GAV in short. +(Please note that artifact coordinates have more fields, but for brevity we still call the +coordinates "GAV", not "GAVCE"). The artifact coordinates uniquely identify an artifact, +but do not specify anything about its source. It is up to Maven to figure out (or you to tell Maven +how to figure out) how and from where to retrieve the artifact. -A word about uniqueness: as stated above, GAV coordinates uniquely identifies artifact, but only **within one repository**. -It is clearly possible (but discouraged) to have multiple repositories with overlapping content (so R1 and R2 both -contain artifact with same GAV). If those files are not-identical (truly, ie. hash wise), it may cause severe +A word about uniqueness: as stated above, GAV coordinates uniquely identify an artifact, but only **within one repository**. +Different repositories can contain artifacts with the same GAV. (This is normal with +mirror repositories.) If those files are not identical, it can cause severe issues without you noticing it. In short, these cases should be avoided. -While Maven internally uses the notion of "artifact" thoroughly (just look at sources!), end users may never hit this term. -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", "reporting 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 id | -| version | The artifact version (linked w/ baseVersion) | -| baseVersion | The artifact base version (linked w/ version) | -| classifier | The artifact distinguishing classifier (optional) | -| extension | The artifact extension (default: "jar") | - -One property worth explaining is a bit of special one: `baseVersion` that is actually derived/linked to -`version` (or the other way around, depending on the context): for release artifacts, it holds the same value as -`version`, whereas for snapshot artifacts, it holds the "non-timestamped snapshot version". For example, -for snapshot version "1.0-20220119.164608-1", the `baseVersion` would have the value "1.0-SNAPSHOT". -So, `version` and `baseVersion` are linked, derived from each other, but **they have different values only in +The artifacts that Maven uses internally have the following properties: + +| Name | Description | +|-------------|-------------------------------------------------| +| groupId | The artifact group | +| artifactId | The artifact ID | Review Comment: I'm not sure that's accurate. I'd prefer to introduce new concept like name here ########## content/markdown/repositories/artifacts.md: ########## @@ -19,55 +19,48 @@ specific language governing permissions and limitations under the License. --> -An Artifact is "anything" (any file) that can be addressed using its coordinates, and Maven downloads, installs or -deploys for you. Most of them are POMs and JARs but -an artifact can be really anything. A very important thing about artifacts is that they have coordinates, +An artifact is a file (more precisely, a sequence of bytes) that can be addressed using its coordinates +and which Maven downloads, installs, or deploys for you. Most artifacts are POMs and JARs, but +an artifact can be really any file. 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 coordinates 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). +Artifact coordinates are most often represented as `groupId:artifactId:version`, or GAV in short. +(Please note that artifact coordinates have more fields, but for brevity we still call the +coordinates "GAV", not "GAVCE"). The artifact coordinates uniquely identify an artifact, +but do not specify anything about its source. It is up to Maven to figure out (or you to tell Maven +how to figure out) how and from where to retrieve the artifact. -A word about uniqueness: as stated above, GAV coordinates uniquely identifies artifact, but only **within one repository**. -It is clearly possible (but discouraged) to have multiple repositories with overlapping content (so R1 and R2 both -contain artifact with same GAV). If those files are not-identical (truly, ie. hash wise), it may cause severe +A word about uniqueness: as stated above, GAV coordinates uniquely identify an artifact, but only **within one repository**. +Different repositories can contain artifacts with the same GAV. (This is normal with +mirror repositories.) If those files are not identical, it can cause severe issues without you noticing it. In short, these cases should be avoided. -While Maven internally uses the notion of "artifact" thoroughly (just look at sources!), end users may never hit this term. -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", "reporting 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 id | -| version | The artifact version (linked w/ baseVersion) | -| baseVersion | The artifact base version (linked w/ version) | -| classifier | The artifact distinguishing classifier (optional) | -| extension | The artifact extension (default: "jar") | - -One property worth explaining is a bit of special one: `baseVersion` that is actually derived/linked to -`version` (or the other way around, depending on the context): for release artifacts, it holds the same value as -`version`, whereas for snapshot artifacts, it holds the "non-timestamped snapshot version". For example, -for snapshot version "1.0-20220119.164608-1", the `baseVersion` would have the value "1.0-SNAPSHOT". -So, `version` and `baseVersion` are linked, derived from each other, but **they have different values only in +The artifacts that Maven uses internally have the following properties: + +| Name | Description | +|-------------|-------------------------------------------------| +| groupId | The artifact group | Review Comment: done ########## content/markdown/repositories/artifacts.md: ########## @@ -19,55 +19,48 @@ specific language governing permissions and limitations under the License. --> -An Artifact is "anything" (any file) that can be addressed using its coordinates, and Maven downloads, installs or -deploys for you. Most of them are POMs and JARs but -an artifact can be really anything. A very important thing about artifacts is that they have coordinates, +An artifact is a file (more precisely, a sequence of bytes) that can be addressed using its coordinates +and which Maven downloads, installs, or deploys for you. Most artifacts are POMs and JARs, but +an artifact can be really any file. 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 coordinates 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). +Artifact coordinates are most often represented as `groupId:artifactId:version`, or GAV in short. +(Please note that artifact coordinates have more fields, but for brevity we still call the +coordinates "GAV", not "GAVCE"). The artifact coordinates uniquely identify an artifact, +but do not specify anything about its source. It is up to Maven to figure out (or you to tell Maven +how to figure out) how and from where to retrieve the artifact. Review Comment: CoC doesn't specify which repository to load artifacts from, especially when local mirrors are in play. That's usually off in settings somewhere. -- 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-unsubscr...@maven.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
