vy commented on code in PR #2806: URL: https://github.com/apache/logging-log4j2/pull/2806#discussion_r1708684359
########## src/site/antora/modules/ROOT/nav.adoc: ########## @@ -63,6 +64,7 @@ ** xref:manual/garbagefree.adoc[] .References +* xref:artifacts.adoc[Artifact reference] Review Comment: I am a little bit reluctant with this change. That is, we always referred to our artifacts as `components`. We even have a dedicated section for that. I find it confusing that we duplicate the terminology here. I would prefer 1. Renaming `artifacts.adoc` to `components.adoc` (`partials/artifacts` should better be renamed too) 2. Removing this link and instead linking to `components.adoc` from the `Components` bullet WDYT? ########## src/site/antora/modules/ROOT/nav.adoc: ########## @@ -38,6 +37,8 @@ *** xref:manual/thread-context.adoc[] ** xref:manual/messages.adoc[] ** xref:manual/flowtracing.adoc[] +* xref:manual/implementation.adoc[] Review Comment: ```suggestion * xref:manual/implementation.adoc[Implementation] ``` ########## src/site/antora/modules/ROOT/pages/manual/implementation.adoc: ########## @@ -0,0 +1,37 @@ +//// + 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. +//// + += Standard Implementation + +The standard implementation of the xref:manual/api.adoc[] is called Log4j Core. Review Comment: ```suggestion The reference implementation of the xref:manual/api.adoc[] is called Log4j Core. ``` ########## src/site/antora/modules/ROOT/pages/manual/implementation.adoc: ########## @@ -0,0 +1,37 @@ +//// + 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. +//// + += Standard Implementation Review Comment: ```suggestion = Reference implementation ``` ########## src/site/antora/modules/ROOT/pages/artifacts.adoc: ########## @@ -0,0 +1,585 @@ +//// + 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 reference + +The Log4j 2 distribution contains the following artifacts: + +[#log4j-bom] +== `log4j-bom` + +A public Bill-of-Materials that manages all the versions of Log4j artifacts. +You can import the BOM in your build tool of preference: + +include::partial$artifacts/log4j-bom.adoc[] + +[#log4j] +== `log4j` + +A private Bill-of-Materials used during the compilation and testing of the project. + +[CAUTION] +==== +Do not use this artifact, since it also manages versions of **third-party** projects. +Use <<log4j-bom>> instead. +==== + +[#log4j-12-api] +== `log4j-1.2-api` + +[cols="1h,5"] +|=== +| JPMS module +| `org.apache.log4j` +|=== + +The `log4j-1.2-api` artifact contains several tools to help users migrate from Log4j 1 to Log4j 2. + +See xref:migrate-from-log4j1.adoc#option-1-use-the-log4j-1-x-bridge-log4j-1-2-api[Log4j 1 to Log4j 2 Bridge] for details. + +include::partial$artifacts/log4j-1.2-api.adoc[] + +[#log4j-api] +== `log4j-api` + +[cols="1h,5"] +|=== +| JPMS module +| `org.apache.logging.log4j` +|=== + +The `log4j-api` artifact contains the xref:manual/api.adoc[]. + +See xref:manual/api.adoc[] for more details. + +include::partial$artifacts/log4j-api.adoc[] + +[#log4j-api-test] +== `log4j-api-test` + +[cols="1h,5"] +|=== +| JPMS module +| `org.apache.logging.log4j.test` +|=== + +The `log4j-api-test` artifact contains test fixtures useful to test Log4j API implementations. + +include::partial$artifacts/log4j-api-test.adoc[] + +[#log4j-appserver] +== `log4j-appserver` + +[cols="1h,5"] +|=== +| JPMS module +| `org.apache.logging.log4j.appserver` +|=== + +The `log4j-appserver` artifact contains: + +* A bridge from Tomcat JULI to the Log4j API. +See xref:jakarta.adoc#replace-tomcat[Replacing Tomcat logging system] for more information. +* A bridge from Jetty 9 logging API to the Log4j API. +See xref:jakarta.adoc#replace-jetty[Replacing Jetty logging system] for more information + +include::partial$artifacts/log4j-appserver.adoc[] + +[#log4j-cassandra] +== `log4j-cassandra` + +[cols="1h,5"] +|=== +| JPMS module +| `org.apache.logging.log4j.cassandra` +|=== + +The `log4j-cassandra` artifact contains an xref:manual/appenders.adoc[appender] for the +https://cassandra.apache.org/_/index.html[Apache Cassandra] +database. + +See xref:manual/appenders/database.adoc#CassandraAppender[Cassandra Appender] for more information. + +include::partial$artifacts/log4j-cassandra.adoc[] + +[#log4j-core] +== `log4j-core` + +[cols="1h,5"] +|=== +| JPMS module +| `org.apache.logging.log4j.core` +|=== + +The `log4j-core` artifact contains the standard implementation of the xref:manual/api.adoc[]. Review Comment: ```suggestion The `log4j-core` artifact contains the reference implementation of the xref:manual/api.adoc[]. ``` ########## src/site/antora/modules/ROOT/nav.adoc: ########## @@ -38,6 +37,8 @@ *** xref:manual/thread-context.adoc[] ** xref:manual/messages.adoc[] ** xref:manual/flowtracing.adoc[] +* xref:manual/implementation.adoc[] +* xref:manual/architecture.adoc[] Review Comment: Since we explicitly create an API-vs-Implementation separation in the menu, shouldn't we nest the following under the `Implementation` bullet? - Architecture - Configuration - Extending ########## src/site/antora/modules/ROOT/pages/artifacts.adoc: ########## @@ -0,0 +1,585 @@ +//// + 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 reference + +The Log4j 2 distribution contains the following artifacts: + +[#log4j-bom] +== `log4j-bom` + +A public Bill-of-Materials that manages all the versions of Log4j artifacts. +You can import the BOM in your build tool of preference: + +include::partial$artifacts/log4j-bom.adoc[] + +[#log4j] +== `log4j` + +A private Bill-of-Materials used during the compilation and testing of the project. + +[CAUTION] +==== +Do not use this artifact, since it also manages versions of **third-party** projects. +Use <<log4j-bom>> instead. +==== + Review Comment: Please remove this. There is no point in disclosing an artifact and telling people to not use it. ```suggestion ``` ########## src/site/antora/modules/ROOT/pages/artifacts.adoc: ########## @@ -0,0 +1,585 @@ +//// + 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 reference + +The Log4j 2 distribution contains the following artifacts: + +[#log4j-bom] +== `log4j-bom` + +A public Bill-of-Materials that manages all the versions of Log4j artifacts. +You can import the BOM in your build tool of preference: + +include::partial$artifacts/log4j-bom.adoc[] + +[#log4j] +== `log4j` + +A private Bill-of-Materials used during the compilation and testing of the project. + +[CAUTION] +==== +Do not use this artifact, since it also manages versions of **third-party** projects. +Use <<log4j-bom>> instead. +==== + +[#log4j-12-api] +== `log4j-1.2-api` + +[cols="1h,5"] +|=== +| JPMS module +| `org.apache.log4j` +|=== + +The `log4j-1.2-api` artifact contains several tools to help users migrate from Log4j 1 to Log4j 2. + +See xref:migrate-from-log4j1.adoc#option-1-use-the-log4j-1-x-bridge-log4j-1-2-api[Log4j 1 to Log4j 2 Bridge] for details. + +include::partial$artifacts/log4j-1.2-api.adoc[] + +[#log4j-api] +== `log4j-api` + +[cols="1h,5"] +|=== +| JPMS module +| `org.apache.logging.log4j` +|=== + +The `log4j-api` artifact contains the xref:manual/api.adoc[]. + +See xref:manual/api.adoc[] for more details. + +include::partial$artifacts/log4j-api.adoc[] + +[#log4j-api-test] +== `log4j-api-test` + +[cols="1h,5"] +|=== +| JPMS module +| `org.apache.logging.log4j.test` +|=== + +The `log4j-api-test` artifact contains test fixtures useful to test Log4j API implementations. + +include::partial$artifacts/log4j-api-test.adoc[] + +[#log4j-appserver] +== `log4j-appserver` + +[cols="1h,5"] +|=== +| JPMS module +| `org.apache.logging.log4j.appserver` +|=== + +The `log4j-appserver` artifact contains: + +* A bridge from Tomcat JULI to the Log4j API. +See xref:jakarta.adoc#replace-tomcat[Replacing Tomcat logging system] for more information. +* A bridge from Jetty 9 logging API to the Log4j API. +See xref:jakarta.adoc#replace-jetty[Replacing Jetty logging system] for more information + +include::partial$artifacts/log4j-appserver.adoc[] + +[#log4j-cassandra] +== `log4j-cassandra` + +[cols="1h,5"] +|=== +| JPMS module +| `org.apache.logging.log4j.cassandra` +|=== + +The `log4j-cassandra` artifact contains an xref:manual/appenders.adoc[appender] for the +https://cassandra.apache.org/_/index.html[Apache Cassandra] +database. + +See xref:manual/appenders/database.adoc#CassandraAppender[Cassandra Appender] for more information. + +include::partial$artifacts/log4j-cassandra.adoc[] + +[#log4j-core] +== `log4j-core` + +[cols="1h,5"] +|=== +| JPMS module +| `org.apache.logging.log4j.core` +|=== + +The `log4j-core` artifact contains the standard implementation of the xref:manual/api.adoc[]. + +See xref:manual/implementation.adoc[] for more details. + +include::partial$artifacts/log4j-core.adoc[] + +[#log4j-core-test] +== `log4j-core-test` + +[cols="1h,5"] +|=== +| JPMS module +| `org.apache.logging.log4j.core.test` +|=== + +The `log4j-core-test` artifact contains test fixtures useful to xref:manual/extending.adoc[extend the standard implementation]. Review Comment: ```suggestion The `log4j-core-test` artifact contains test fixtures useful to xref:manual/extending.adoc[extend the reference implementation]. ``` ########## src/site/antora/modules/ROOT/pages/artifacts.adoc: ########## @@ -0,0 +1,585 @@ +//// + 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 reference Review Comment: As I stated earlier, I am a little bit reluctant with the word `Artifact`, in particular, in the menu. We always referred to our support _artifacts_/_modules_ as _components_. I don't see a compelling reason to move away from that nomenclature. ```suggestion = Components ``` -- 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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
