Release Notes for 2.0.0.

Author: carlosame

RELEASE_NOTES.txt

@@ -2,14 +2,12 @@
                             CSS4J RELEASE NOTES
                             ===================
 
-Release 2.0.0-beta1 - November 11, 2019
----------------------------------------
+Release 2.0.0 - December 4, 2019
+--------------------------------
 
- It is the first beta of the 2.0 (master) branch, looking forwards a final 2.0.0
-release in December 2019. Features NSAC 2.0 and a new Object Model Value API; it
+ This new major release features NSAC 2.0 and a new Object Model Value API; it
 is not backwards-compatible with 1.0, but the new 2.0 APIs are more appropriate
-to deal with modern CSS. Any new development should use the 2.0 API (and hence
-the interest in releasing it as soon as possible).
+to deal with modern CSS. Any new development should use the 2.0 API.
 
  NSAC 2.0 no longer inherits from stuff in the org.w3c.css.sac package (provided
 by the -not needed anymore- sac.jar file) but is an independent API, with its
@@ -34,12 +32,44 @@ ease the transition (for example I keep getCssValueType() to retrieve the value
 category, instead of a more proper getCategory()).
 
  Another important change is that the source-level compatibility is now for Java
-version 8 instead of 7. Comments about the new APIs are welcome.
+SE version 8 instead of 7. Comments about the new APIs are welcome.
 
  Many 2.0 patches do not apply to 1.0 which makes it difficult to maintain. As a
-consequence, the end of life for 1.0.x would happen relatively early in 2020
-unless somebody volunteers for maintaining it (which would probably be a waste
-of time).
+consequence, the end of life for 1.0 shall happen in March 5, 2020 unless
+somebody volunteers for maintaining it (which would probably be a waste of time).
+
+
+Upgrading from 1.0
+------------------
+ The extended CSS interfaces in 1.0 ('css' and 'nsac' packages) have now adopted
+the names of the interfaces that they were extending, due to the fact that they
+are no longer an extension but a full fork. This means that if you are using
+interfaces prefixed with 'Extended' or having the '2' suffix from those 'css'
+and 'nsac' packages, you need to remove that prefix/suffix to begin the upgrade,
+and then use the interfaces from css4j instead of the old W3C ones. Note that
+this is only for the CSS interfaces, so the 'Extended'-prefixed interfaces in
+the 'doc.dom' package were not changed.
+
+ SAC/NSAC 1.x users need to look closely at the new CSSHandler interface, and to
+the changes in LexicalUnit; the rest of the API changes should be easy to apply.
+The type identifiers in 2.0 use enumerations instead of integers (CSS unit
+identifiers are now separate from type identifiers and are still integer).
+
+ If you are using the CSSValue API, the upgrade is non-trivial and you should
+look at the new interfaces. In many cases where you were using the
+CSSPrimitiveValue interface, you should be using the new CSSTypedValue, although
+sometimes the renewed CSSValue type may be all that you need.
+
+ For example, calls to CSSPrimitiveValue.getRGBColorValue() should be changed to
+CSSTypedValue.toRGBColorValue(), but be sure that the type is a COLOR value in
+the RGB space before trying to edit the color (and you can use
+RGBColorValue.getRGBColorValue() to access the RGBAColor object).
+
+ DOM4J users should be aware that the document factory no longer automatically
+loads a default User Agent sheet. This backwards-incompatible change may seem
+gratuitous, but the old behaviour has shown to be problematic for users.
+
+ Finally, be sure that you are able to use Java SE 8 or higher.
 
 
 Description
@@ -51,14 +81,14 @@ different licensing).
 
  The functionality in this library can be divided in the following areas:
 
-- An implementation of the standard W3C CSS Object Model API, that allows 
-  to get computed styles for elements in a DOM Document. A DOM implementation 
-  is available, as well as a DOM4J backend (module css4j-dom4j) and also a DOM
-  wrapper that can be used with an external DOM implementation.
-- An extension to the base W3C APIs.
-- A device profile API to encapsulate target device-specific information. An
-  example implementation based on Java2D is in the 'render' module of the main
-  Carte project.
+- A CSSOM API very similar to the standard W3C CSS Object Model API, that allows
+  accessing the CSS information (style sheets, inline styles, etc.) in a DOM
+  Document, as well as getting computed styles for its elements.
+- A CSS-enabled native DOM implementation.
+- A DOM wrapper that can be used with an external DOM implementation.
+- A DOM4J backend (module css4j-dom4j) which uses documents and elements that
+  extend those of dom4j (for those who are comfortable with dom4j).
+- A device profile API to encapsulate target device-specific information.
 - A few AWT helper classes (AWT module).
 - Some helper XML-DTD classes.