LOG4J2-2298: Add changelog to site
Project: http://git-wip-us.apache.org/repos/asf/logging-log4j-scala/repo Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j-scala/commit/f8d3f94b Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j-scala/tree/f8d3f94b Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j-scala/diff/f8d3f94b Branch: refs/heads/master Commit: f8d3f94b89f9f64c729f6b818677ccb4a0cfe9c3 Parents: 5be05b5 Author: Matt Sicker <[email protected]> Authored: Fri Mar 30 16:46:08 2018 -0500 Committer: Matt Sicker <[email protected]> Committed: Fri Mar 30 16:46:08 2018 -0500 ---------------------------------------------------------------------- src/asciidoctor/changes.adoc | 42 +++++++++++++++++++++++ src/asciidoctor/index.adoc | 57 ++----------------------------- src/asciidoctor/usage.adoc | 70 +++++++++++++++++++++++++++++++++++++++ src/changes/changes.xml | 60 --------------------------------- 4 files changed, 115 insertions(+), 114 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/logging-log4j-scala/blob/f8d3f94b/src/asciidoctor/changes.adoc ---------------------------------------------------------------------- diff --git a/src/asciidoctor/changes.adoc b/src/asciidoctor/changes.adoc new file mode 100644 index 0000000..890263a --- /dev/null +++ b/src/asciidoctor/changes.adoc @@ -0,0 +1,42 @@ +//// + 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. +//// +== ChangeLog + +=== Version 11.1 + +[vertical] +New Features:: +[horizontal] +LOG4J2-2298::: Add changelog to site. +LOG4J2-2293::: Add required license files to SBT output artifacts. +LOG4J2-2296::: Add sbt-site plugin and website configuration. +LOG4J2-2291::: Add Jenkins pipeline for SBT build. + +[vertical] +Bug Fixes:: None. + +[vertical] +Changes:: +[horizontal] +LOG4J2-2290::: Update Log4j from 2.9.1 to 2.11.0. +LOG4J2-1995::: Update log4j-api-scala_2.11 from Scala 2.11.8 to 2.11.11. +LOG4J2-1996::: Update log4j-api-scala_2.12 from Scala 2.12.1 to 2.12.3. +LOG4J2-2115::: Update Log4j dependency from 2.8.1 to 2.9.1. +LOG4J2-2116::: Update log4j-api-scala_2.12 from Scala 2.12.3 to 2.12.4. + +[vertical] +Removed:: None. http://git-wip-us.apache.org/repos/asf/logging-log4j-scala/blob/f8d3f94b/src/asciidoctor/index.adoc ---------------------------------------------------------------------- diff --git a/src/asciidoctor/index.adoc b/src/asciidoctor/index.adoc index b9595af..33e0ceb 100644 --- a/src/asciidoctor/index.adoc +++ b/src/asciidoctor/index.adoc @@ -15,72 +15,21 @@ limitations under the License. //// = Apache Log4j Scala API +:toc: left Log4j Scala API is a Scala logging facade based on Log4j 2. Support for Scala versions 2.10, 2.11, and 2.12 are provided, and experimental support for pre-release versions of 2.13 is also provided. Log4j Scala API uses Log4j 2.x as its logging backend by default, but this can also be replaced with compatible libraries (e.g., Logback). While this library is not required to use Log4j API in Scala, it does provide idiomatic Scala APIs which are friendlier to use in Scala programs than the Java APIs. -== Usage +include::usage.adoc[] -Log4j Scala API requires Log4j API. An example SBT dependency setup: - -.build.sbt -[source,scala] ----- -libraryDependencies ++= Seq( - "org.apache.logging.log4j" %% "log4j-api-scala" % "11.0", - "org.apache.logging.log4j" % "log4j-api" % "2.11.0", - "org.apache.logging.log4j" % "log4j-core" % "2.11.0" % Runtime) ----- - -Using the Scala API is as simple as mixing in the `Logging` trait to your class. Example: - -[source,scala] ----- -import org.apache.logging.log4j.scala.Logging -import org.apache.logging.log4j.Level - -class MyClass extends BaseClass with Logging { - def doStuff(): Unit = { - logger.info("Doing stuff") - } - def doStuffWithLevel(level: Level): Unit = { - logger(level, "Doing stuff with arbitrary level") - } - def doStuffWithUser(user: User): Unit = { - logger.info(s"Doing stuff with ${user.getName}.") - } -} ----- - -== Configuration - -Log4j Scala API uses https://logging.apache.org/log4j/2.x/manual/configuration.html[Log4j configuration] by default. -This supports XML, properties files, and Java-based builders, as well as JSON and YAML with additional dependencies. - -== Substituting Parameters - -Unlike in Java, Scala provides native functionality for string interpolation https://docs.scala-lang.org/overviews/core/string-interpolation.html[beginning in Scala 2.10]. -As all logger calls are implemented as macros, using string interpolation directly does not require additional if checks. -For example: - -[source,scala] ----- -logger.debug(s"Logging in user ${user.getName} with birthday ${user.calcBirthday}") ----- - -== Logger Names - -Most logging implementations use a hierarchical scheme for matching logger names with logging configuration. -In this scheme the logger name hierarchy is represented by '.' characters in the logger name, in a fashion very similar to the hierarchy used for Java/Scala package names. -The `Logging` trait will automatically name the Logger accordingly to the class it is being used in. +include::changes.adoc[] //// TODO: * Apache logo * Downloads page -* Changelog page * License report * Other reports? * ScalaDocs links http://git-wip-us.apache.org/repos/asf/logging-log4j-scala/blob/f8d3f94b/src/asciidoctor/usage.adoc ---------------------------------------------------------------------- diff --git a/src/asciidoctor/usage.adoc b/src/asciidoctor/usage.adoc new file mode 100644 index 0000000..10fa6b9 --- /dev/null +++ b/src/asciidoctor/usage.adoc @@ -0,0 +1,70 @@ +//// + 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. +//// +== Usage + +Log4j Scala API requires Log4j API. An example SBT dependency setup: + +.build.sbt +[source,scala] +---- +libraryDependencies ++= Seq( + "org.apache.logging.log4j" %% "log4j-api-scala" % "11.0", + "org.apache.logging.log4j" % "log4j-api" % "2.11.0", + "org.apache.logging.log4j" % "log4j-core" % "2.11.0" % Runtime) +---- + +Using the Scala API is as simple as mixing in the `Logging` trait to your class. Example: + +[source,scala] +---- +import org.apache.logging.log4j.scala.Logging +import org.apache.logging.log4j.Level + +class MyClass extends BaseClass with Logging { + def doStuff(): Unit = { + logger.info("Doing stuff") + } + def doStuffWithLevel(level: Level): Unit = { + logger(level, "Doing stuff with arbitrary level") + } + def doStuffWithUser(user: User): Unit = { + logger.info(s"Doing stuff with ${user.getName}.") + } +} +---- + +== Configuration + +Log4j Scala API uses https://logging.apache.org/log4j/2.x/manual/configuration.html[Log4j configuration] by default. +This supports XML, properties files, and Java-based builders, as well as JSON and YAML with additional dependencies. + +== Substituting Parameters + +Unlike in Java, Scala provides native functionality for string interpolation https://docs.scala-lang.org/overviews/core/string-interpolation.html[beginning in Scala 2.10]. +As all logger calls are implemented as macros, using string interpolation directly does not require additional if checks. +For example: + +[source,scala] +---- +logger.debug(s"Logging in user ${user.getName} with birthday ${user.calcBirthday}") +---- + +== Logger Names + +Most logging implementations use a hierarchical scheme for matching logger names with logging configuration. +In this scheme the logger name hierarchy is represented by '.' characters in the logger name, in a fashion very similar to the hierarchy used for Java/Scala package names. +The `Logging` trait will automatically name the Logger accordingly to the class it is being used in. http://git-wip-us.apache.org/repos/asf/logging-log4j-scala/blob/f8d3f94b/src/changes/changes.xml ---------------------------------------------------------------------- diff --git a/src/changes/changes.xml b/src/changes/changes.xml deleted file mode 100644 index f3863eb..0000000 --- a/src/changes/changes.xml +++ /dev/null @@ -1,60 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- vi: set sw=2: --> -<!-- - 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. ---> -<document xmlns="http://maven.apache.org/changes/1.0.0"; - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; - xsi:schemaLocation="http://maven.apache.org/changes/1.0.0 http://maven.apache.org/xsd/changes-1.0.0.xsd";> - <properties> - <title>Changes</title> - </properties> - <body> - <!-- NOTE: the text node in an action element is interpreted as Markdown in the release notes! --> - <!-- The "type" attribute can have the following values: - - "add" - New Feature - - "fix" - Fixed Bug - - "update" - Change - - "remove" - Removed - --> - <release version="11.1" date="2018-MM-DD" description="GA Release 11.1"> - <action issue="LOG4J2-2293" dev="mattsicker" type="add"> - Add required license files to SBT output artifacts. - </action> - <action issue="LOG4J2-2296" dev="mattsicker" type="add"> - Add sbt-site plugin and website configuration. - </action> - <action issue="LOG4J2-2291" dev="mattsicker" type="add"> - Add Jenkins pipeline for SBT build. - </action> - <action issue="LOG4J2-2290" dev="mattsicker" type="update"> - Update Log4j from 2.9.1 to 2.11.0. - </action> - <action issue="LOG4J2-1995" dev="ggregory" type="update"> - Update log4j-api-scala_2.11 from Scala 2.11.8 to 2.11.11. - </action> - <action issue="LOG4J2-1996" dev="ggregory" type="update"> - Update log4j-api-scala_2.12 from Scala 2.12.1 to 2.12.3. - </action> - <action issue="LOG4J2-2115" dev="ggregory" type="update"> - Update Log4j dependency from 2.8.1 to 2.9.1. - </action> - <action issue="LOG4J2-2116" dev="ggregory" type="update"> - Update log4j-api-scala_2.12 from Scala 2.12.3 to 2.12.4. - </action> - </release> - </body> -</document>
