Prep docs for v2.0 release

Author: RohanNagar

CHANGELOG.md

@@ -1,11 +1,11 @@
 # JMail Changelog
 
-## 2.0.0 (Upcoming)
+## 2.0.0
 
 ### Breaking Changes
 
-- By default, `Email#normalized` now lowercases the email address **and** removes any extraneous quotes in the local-part of the address.
-  To revert this behavior so that it behaves the same as v1, use the following:
+- By default, `Email#normalized` now lowercases the email address **and** removes any extraneous quotes in
+  the local-part of the address. To revert this behavior so that it behaves the same as v1, use the following:
 
   ```
   myEmailObject.normalized(
@@ -24,8 +24,13 @@
   Quotes are stripped by default now. If you need to disable quote stripping, use `NormalizationOptionsBuilder#keepQuotes()`.
 
 
-- `FailureReason` was switched from an enum to a class in order to support custom failure reasons, so you cannot
-  use it in a `switch` statement.
+- `FailureReason` was switched from an enum to a class in order to support custom failure reasons, so it is no longer
+  possible to use it in a `switch` statement.
+
+
+- Email addresses that fail validation due to additional rules added to the `EmailValidator` (such as
+  `disallowIpDomain()` or `requireValidMXRecord()`) no longer return a generic `FailureReason.FAILED_CUSTOM_VALIDATION`
+  in the `EmailValidationResult`. Instead, it returns a more specific `FailureReason` depending on the rule.
 
 
 - `FailureReason.MISSING_TOP_LEVEL_DOMAIN` was changed to `FailureReason.MISSING_FINAL_DOMAIN_PART`.
@@ -36,10 +41,6 @@
   that failure reason.
 
 
-- Email addresses that fail validation due to additional rules added to the `EmailValidator` (such as
-  `disallowIpDomain()` or `requireValidMXRecord()`) no longer return a generic `FailureReason.FAILED_CUSTOM_VALIDATION`
-  in the `EmailValidationResult`. Instead, it returns a more specific `FailureReason` depending on the rule. 
-
 ### FailureReason Improvements
 
 #### Changes to the FailureReason supplied for additional rules
@@ -83,10 +84,10 @@ assertEquals(nonGmailFailure, result.getFailureReason());
 #### New Normalization Methods
 
 This version introduces a new `NormalizationOptions` class that is used to provide
-configuration of the behavior of the `Email#normalize()` method. See the table below to see
+configuration of the behavior of the `Email#normalized()` method. See the table below to see
 all the new and existing options.
 
-In v2.0.0, you can use either `Email#normalize()` (with no parameters) or `Email#normalize(NormalizationOptions options)`.
+In v2.0.0, you can use either `Email#normalized()` (with no parameters) or `Email#normalized(NormalizationOptions options)`.
 
 The first method without parameters will return a normalized email address based on the default
 normalization options. The second method allows you to provide your own `NormalizationOptions` at runtime
@@ -109,7 +110,7 @@ Thanks, @Sprokof, for contributing (introducing `removeDots` and `adjustCase` op
 ### Additional Address Formats
 
 Version 2.0.0 introduces new additional email address formats that can be obtained from
-the `Email` object (similar to the `normalize()` method).
+the `Email` object (similar to the `normalized()` method).
 
 - `Email#reference()` returns an MD5 hash of the normalized email address.
 

README.md

@@ -36,10 +36,10 @@ following reasons:
    email address! It clearly is not, as it has two `@` characters. JMail correctly
    considers this address invalid. You can
    [see a full comparison of correctness and try it out for yourself online](https://www.rohannagar.com/jmail/).
-   
+
 2. JMail is **_faster_** than other libraries by, on average, at least
    2x, thanks in part to lack of regex.
-   
+
 3. JMail has **_zero dependencies_** and is very lightweight.
 
 4. JMail is **_modern_**. It is built for Java 8+, and provides many
@@ -65,21 +65,21 @@ Add this library as a dependency in your `pom.xml`:
 <dependency>
   <groupId>com.sanctionco.jmail</groupId>
   <artifactId>jmail</artifactId>
-  <version>1.6.2</version>
+  <version>2.0.0</version>
 </dependency>
 ```
 
 Or in your `build.gradle`:
 
 ```groovy
-implementation 'com.sanctionco.jmail:jmail:1.6.2'
+implementation 'com.sanctionco.jmail:jmail:2.0.0'
 ```
 
 ## Usage
 
 ### Standard Email Validation
 
-To perform standard email validation, use the static methods
+To perform standard, RFC-compliant email validation, you can use the static methods
 available in `JMail`. For example, to test validation:
 
 ```java
@@ -133,7 +133,8 @@ EmailValidator validator = JMail.strictValidator()
     // Require that the top-level-domain is ".com"
     .requireOnlyTopLevelDomains(TopLevelDomain.DOT_COM)
     // Require that the local-part starts with "allowed"
-    .withRule(email -> email.localPart().startsWith("allowed"));
+    .withRule(email -> email.localPart().startsWith("allowed"),
+            new FailureReason("DOES_NOT_START_WITH_ALLOWED"));
 
 boolean valid = validator.isValid("allowed-email@test.com");
 boolean invalidWithoutTld = validator.isValid("allowed@test");
@@ -193,27 +194,50 @@ JMail.tryParse("test@example.com")
         () -> log.error("Could not send email to invalid email"));
 ```
 
-#### Get a normalized version of the email address
+#### Get different versions of the email address
 
 ```java
-// Get a normalized email address without any comments
+// Get a normalized email address
 Optional<String> normalized = JMail.tryParse("admin(comment)@mysite.org")
     .map(Email::normalized);
 
 // normalized == Optional.of("admin@mysite.org")
 ```
 
 ```java
-// Get a normalized email address and strip quotes if the address would
-// still be valid
-Optional<String> normalized = JMail.tryParse("\"test.1\"@mysite.org")
-        .map(e -> e.normalized(true));
+// Get a normalized email address and remove any sub-addressing when normalizing
+Optional<String> normalized = JMail.tryParse("test.1+mytag@mysite.org")
+        .map(e -> e.normalized(
+            NormalizationOptions.builder()
+                    .removeSubAddress()
+                    .build()));
 
 // normalized == Optional.of("test.1@mysite.org")
 ```
 
-> **Note:** You can also set the `-Djmail.normalize.strip.quotes=true` JVM property to
-strip quotes when calling `normalized()` without parameters.
+```java
+// Get a reference (MD5 hash) of the email address
+Optional<String> reference = JMail.tryParse("test@gmail.com")
+        .map(Email::reference);
+
+// redacted == Optional.of("1aedb8d9dc4751e229a335e371db8058");
+```
+
+```java
+// Get a redacted version of the email address
+Optional<String> redacted = JMail.tryParse("test@gmail.com")
+        .map(Email::redacted);
+
+// redacted == Optional.of("{a94a8fe5ccb19ba61c4c0873d391e987982fbbd3}@gmail.com");
+```
+
+```java
+// Get a munged version of the email address
+Optional<String> redacted = JMail.tryParse("test@gmail.com")
+        .map(Email::munged);
+
+// redacted == Optional.of("te*****@gm*****");
+```
 
 ### Additional Validation Rules
 
@@ -325,6 +349,17 @@ other than ASCII characters.
 JMail.validator().requireAscii();
 ```
 
+#### Allow Nonstandard Dots in the Local-Part
+
+While technically disallowed under published RFCs, some email providers (ex: GMail)
+consider email addresses that have local-parts that start with or end with a dot `.` character
+as valid. For example, GMail considers `.my.email.@gmail.com` valid, even though it is not
+actually valid according to RFC.
+
+```java
+JMail.validator().allowNonstandardDots();
+```
+
 ### Bonus: IP Address Validation
 
 Since validating email addresses requires validation of IP addresses,
@@ -379,8 +414,8 @@ Optional<String> validated = InternetProtocolAddress.validate(ipv4);
 
 // The validate() method allows for convenience such as:
 String ip = InternetProtocolAddress
-    .validate("notvalid")
-    .orElse("0.0.0.0");
+        .validate("notvalid")
+        .orElse("0.0.0.0");
 ```
 
 ```java
@@ -390,8 +425,8 @@ Optional<String> validated = InternetProtocolAddress.validate(ipv6);
 
 // The validate() method allows for convenience such as:
 String ip = InternetProtocolAddress
-    .validate("notvalid")
-    .orElse("2001:db8::1234:5678");
+        .validate("notvalid")
+        .orElse("2001:db8::1234:5678");
 ```
 
 ### Contributing