Close #91: add java-time.api, soft deprecate java-time ns

Author: frenchy64

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## NEXT
+
+Due to [#91](https://github.com/dm3/clojure.java-time/issues/91), the main `java-time`
+namespace has been deprecated. A new namespace `java-time.api` has been created
+
+Note that this change is entirely optional---`java-time` and `java-time.api` will continue to be in sync and may coexist.
+
+See [the docstring for `java-time`](https://dm3.github.io/clojure.java-time/java-time.html) for more details.
+
 ## 1.0.0
 
 Released 2022-11-24.

README.md

@@ -4,6 +4,9 @@
 
 A Clojure wrapper for Java 8 Date-Time API.
 
+> Note: This library has no relation Clojure's (or Java's) core team.
+> It's naming is legacy and preserved for backwards compatibility reasons.
+
 ## Rationale
 
 Main goals:
@@ -38,7 +41,7 @@ is purely on the merits of a broader feature set.
 
 ## Documentation
 
-* [API](http://dm3.github.io/clojure.java-time/)
+* [API](https://dm3.github.io/clojure.java-time/)
 * [![cljdoc badge](https://cljdoc.org/badge/clojure.java-time/clojure.java-time)](https://cljdoc.org/d/clojure.java-time/clojure.java-time/CURRENT)
 
 ## What's different in Java Time API?
@@ -50,9 +53,9 @@ complicated than it has to be. Also, a few concepts have faulty designs which
 lead to hard to fix bugs and misuse. You can see the birds-eye view of changes
 and some of the rationale on the author's (Stephen Colebourne) blog:
 
-* [what's wrong with Joda-Time](http://blog.joda.org/2009/11/why-jsr-310-isn-joda-time_4941.html),
-* [when you should use Java-Time](http://blog.joda.org/2014/07/threeten-backport-vs-joda-time.html)
-* [what's different in Java-Time](http://blog.joda.org/2014/11/converting-from-joda-time-to-javatime.html).
+* [what's wrong with Joda-Time](https://blog.joda.org/2009/11/why-jsr-310-isn-joda-time_4941.html),
+* [when you should use Java-Time](https://blog.joda.org/2014/07/threeten-backport-vs-joda-time.html)
+* [what's different in Java-Time](https://blog.joda.org/2014/11/converting-from-joda-time-to-javatime.html).
 
 You can also take a look at a [comprehensive comparison](http://time4j.net/tutorial/appendix.html) by the
 [Time4J](http://time4j.net/) authors.
@@ -61,28 +64,28 @@ You can also take a look at a [comprehensive comparison](http://time4j.net/tutor
 
 Add the following dependency to your `deps.edn`
 ```clj
-clojure.java-time/clojure.java-time {:mvn/version "0.3.3"}
+clojure.java-time/clojure.java-time {:mvn/version "1.0.0"}
 ```
 
 or to your `project.clj` or `build.boot`:
 
 ```clj
-[clojure.java-time "0.3.3"]
+[clojure.java-time "1.0.0"]
 ```
 
 The [API](https://dm3.github.io/clojure.java-time/) of the Clojure.Java-Time
-consists of one namespace, namely `java-time`.  For the purposes of this guide,
+consists of one namespace, namely `java-time.api`.  For the purposes of this guide,
 we will `require` the main namespace:
 
 ```clj
-(require '[java-time :as jt]
+(require '[java-time.api :as jt]
          ;; for REPL experimentation
          'java-time.repl)
 ```
 
 ### Concept run-through
 
-Java Time API may seem daunting. Instead of a single `java.util.Date` you have
+The Java Time API may seem daunting. Instead of a single `java.util.Date` you have
 a `ZonedDateTime`, `OffsetDateTime`, `LocalDateTime`, `Instant`, and other
 types. You would be well served by reading the official documentation for the
 [Java Time API](https://docs.oracle.com/javase/tutorial/datetime/iso/index.html), 
@@ -96,11 +99,11 @@ are used to represent human-based dates/times. They are a good fit for represent
 the time of various events:
 
 * `LocalDate` - birthday, holiday
-    * see [`jt/local-date`](http://dm3.github.io/clojure.java-time/java-time.html#var-local-date)
+    * see [`jt/local-date`](https://dm3.github.io/clojure.java-time/java-time.api.html#var-local-date)
 * `LocalTime` - bus schedule, opening time of a shop
-    * see [`jt/local-time`](http://dm3.github.io/clojure.java-time/java-time.html#var-local-time)
+    * see [`jt/local-time`](https://dm3.github.io/clojure.java-time/java-time.api.html#var-local-time)
 * `LocalDateTime` - start of a competition
-    * see [`jt/local-date-time`](http://dm3.github.io/clojure.java-time/java-time.html#var-local-date-time)
+    * see [`jt/local-date-time`](https://dm3.github.io/clojure.java-time/java-time.api.html#var-local-date-time)
 
 Example usage:
 
@@ -119,9 +122,9 @@ Example usage:
 
 There are two types which deal with zones: 
 * `OffsetDateTime`
-  * see [`jt/offset-date-time`](https://dm3.github.io/clojure.java-time/java-time.html#var-offset-date-time)
+  * see [`jt/offset-date-time`](https://dm3.github.io/clojure.java-time/java-time.api.html#var-offset-date-time)
 * `ZonedDateTime`
-  * see [`jt/zoned-date-time`](https://dm3.github.io/clojure.java-time/java-time.html#var-zoned-date-time)
+  * see [`jt/zoned-date-time`](https://dm3.github.io/clojure.java-time/java-time.api.html#var-zoned-date-time)
 
 They do pretty much what you would expect from their name.
 You can think of the `Offset` time as a more concrete version of the `Zoned`
@@ -141,8 +144,8 @@ year due to DST or governmental regulations.
 
 Offset/Zone times only take the offset/zone as the last arguments for the
 maximum arity constructor. You can influence the zone/offset by using the
-[`jt/with-zone`](https://dm3.github.io/clojure.java-time/java-time.html#var-with-zone)
-or [`jt/with-offset`](https://dm3.github.io/clojure.java-time/java-time.html#var-with-offset) functions, like so:
+[`jt/with-zone`](https://dm3.github.io/clojure.java-time/java-time.api.html#var-with-zone)
+or [`jt/with-offset`](https://dm3.github.io/clojure.java-time/java-time.api.html#var-with-offset) functions, like so:
 
 ```clj
 (jt/with-zone (jt/zoned-date-time 2015 10) "UTC")

docs/CHANGELOG.html

@@ -1,6 +1,10 @@
 <!DOCTYPE html PUBLIC ""
     "">
-<html><head><meta charset="UTF-8" /><title>Changelog</title><link rel="stylesheet" type="text/css" href="css/default.css" /><link rel="stylesheet" type="text/css" href="css/highlight.css" /><script type="text/javascript" src="js/highlight.min.js"></script><script type="text/javascript" src="js/jquery.min.js"></script><script type="text/javascript" src="js/page_effects.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body><div id="header"><h2>Generated by <a href="https://github.com/weavejester/codox">Codox</a></h2><h1><a href="index.html"><span class="project-title"><span class="project-name">Clojure.java-time</span> <span class="project-version">1.0.0</span></span></a></h1></div><div class="sidebar primary"><h3 class="no-link"><span class="inner">Project</span></h3><ul class="index-link"><li class="depth-1 "><a href="index.html"><div class="inner">Index</div></a></li></ul><h3 class="no-link"><span class="inner">Topics</span></h3><ul><li class="depth-1 "><a href="README.html"><div class="inner"><span>Clojure.Java-Time</span></div></a></li><li class="depth-1  current"><a href="CHANGELOG.html"><div class="inner"><span>Changelog</span></div></a></li></ul><h3 class="no-link"><span class="inner">Namespaces</span></h3><ul><li class="depth-1"><a href="java-time.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>java-time</span></div></a></li><li class="depth-2"><a href="java-time.repl.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>repl</span></div></a></li></ul></div><div class="document" id="content"><div class="doc"><div class="markdown"><h1><a href="#changelog" id="changelog"></a>Changelog</h1>
+<html><head><meta charset="UTF-8" /><title>Changelog</title><link rel="stylesheet" type="text/css" href="css/default.css" /><link rel="stylesheet" type="text/css" href="css/highlight.css" /><script type="text/javascript" src="js/highlight.min.js"></script><script type="text/javascript" src="js/jquery.min.js"></script><script type="text/javascript" src="js/page_effects.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body><div id="header"><h2>Generated by <a href="https://github.com/weavejester/codox">Codox</a></h2><h1><a href="index.html"><span class="project-title"><span class="project-name">Clojure.java-time</span> <span class="project-version">1.1.0-SNAPSHOT</span></span></a></h1></div><div class="sidebar primary"><h3 class="no-link"><span class="inner">Project</span></h3><ul class="index-link"><li class="depth-1 "><a href="index.html"><div class="inner">Index</div></a></li></ul><h3 class="no-link"><span class="inner">Topics</span></h3><ul><li class="depth-1 "><a href="README.html"><div class="inner"><span>Clojure.Java-Time</span></div></a></li><li class="depth-1  current"><a href="CHANGELOG.html"><div class="inner"><span>Changelog</span></div></a></li></ul><h3 class="no-link"><span class="inner">Namespaces</span></h3><ul><li class="depth-1"><a href="java-time.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>java-time</span></div></a></li><li class="depth-2 branch"><a href="java-time.api.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>api</span></div></a></li><li class="depth-2"><a href="java-time.repl.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>repl</span></div></a></li></ul></div><div class="document" id="content"><div class="doc"><div class="markdown"><h1><a href="#changelog" id="changelog"></a>Changelog</h1>
+<h2><a href="#next" id="next"></a>NEXT</h2>
+<p>Due to <a href="https://github.com/dm3/clojure.java-time/issues/91">#91</a>, the main <code>java-time</code> namespace has been deprecated. A new namespace <code>java-time.api</code> has been created</p>
+<p>Note that this change is entirely optional—<code>java-time</code> and <code>java-time.api</code> will continue to be in sync and may coexist.</p>
+<p>See <a href="https://dm3.github.io/clojure.java-time/java-time.html">the docstring for <code>java-time</code></a> for more details.</p>
 <h2><a href="#100" id="100"></a>1.0.0</h2>
 <p>Released 2022-11-24.</p>
 <h3><a href="#new-features" id="new-features"></a>New Features</h3>