[isis] branch master updated: ISIS-2435: Commons: writing about.adoc

[ah...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

ahuber pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/isis.git


The following commit(s) were added to refs/heads/master by this push:
     new 3b80737  ISIS-2435: Commons: writing about.adoc
3b80737 is described below

commit 3b80737460b6fa352589a2a37eaeff0c77f7b248
Author: Andi Huber <ah...@apache.org>
AuthorDate: Fri Sep 18 11:53:31 2020 +0200

    ISIS-2435: Commons: writing about.adoc
---
 .../src/main/adoc/modules/commons/pages/about.adoc | 60 +++++++++++++++++++++-
 1 file changed, 59 insertions(+), 1 deletion(-)

diff --git a/commons/src/main/adoc/modules/commons/pages/about.adoc b/commons/src/main/adoc/modules/commons/pages/about.adoc
index a48b17c..27c56fc 100644
--- a/commons/src/main/adoc/modules/commons/pages/about.adoc
+++ b/commons/src/main/adoc/modules/commons/pages/about.adoc
@@ -2,5 +2,63 @@
 
 :Notice: 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 ag [...]
 
-WARNING: TODO
+_Apache Isis Commons_ is a library with utilities, that are shared with the entire 
+_Apache Isis_ ecosystem.
+
+== Motivation
+
+This module was initially created, to remove dependence on 3^rd^ party (general purpose) 
+_Java_ libraries like _Guava_ or _Apache Commons_. This should reduce the likelihood for 
+_Apache Isis_ developers to run into _jar_ version conflicts, when using one of these 
+3^rd^ party libraries. 
+
+It now also allows us to collect utilities in support of common idioms, that we use 
+throughout the _Apache Isis_ ecosystem. 
+
+== Packages
+
+Package structure distinguishes classes either for _internal_ or _public_ use.
+
+=== Public
+
+[source]
+----
+org.apache.isis.commons.* // excluding ...internal.*
+----
+
+Classes meant for public use. For any changes, that break compatibility with older code, 
+we will write migration or release notes to inform developers how to migrate.   
+ 
+=== Internal
+
+[source]
+----
+org.apache.isis.commons.internal.* // internal
+----
+
+Classes meant for framework internal use. By convention these classes are prefixed with 
+an underscore `*_*`, to explicitly indicate their nature.
+
+WARNING: Do *not* use any of the classes provided by these *internal* packages, simply 
+because these may be changed or removed without notice! 
+
+== Install
+
+[source,xml]
+.Maven
+----
+<dependency>
+    <groupId>org.apache.isis.commons</groupId>
+    <artifactId>isis-commons</artifactId>
+    <version>xxx</version>
+</dependency>
+----
+
+[source]
+.Gradle
+----
+compile group: 'org.apache.isis', name: 'isis-commons', version: 'xxx'
+----
+
+