Upgrade 4

4.0-Upgrade.md

@@ -0,0 +1,143 @@
+# Welcome to Whois 4.0!
+
+Whois 4 is a major upgrade compared to Whois 3. This library is now 7 years old, enough mature to offer pretty much all the features you need to perform WHOIS queries.
+
+In these last 7 years the adoption of this library has grown beyond any expectation. Most of the time was spent updating the definitions to stay up to date with the various registrar changes (thanks ICANN for thew newGLTDs...), updating the registry parsers and polishing up the public interface.
+
+For Whois 4 I decided to take a step back, and rewrite some of the internal components of this library to improve performance and readability. As a result of these changes, there are several compatibility breaks with Whois 4 that I'm going to document here.
+
+-- Simone
+
+## What's New
+
+- The Whois client and the Whois parser are now two separate repositories, and they are also distributed as two separate gems:
+
+    - https://github.com/weppos/whois - https://rubygems.org/gems/whois
+    - https://github.com/weppos/whois-parser https://rubygems.org/gems/whois-parser
+
+  There are several reasons behind this change (see [weppos/whois#503](https://github.com/weppos/whois/pull/503)).
+
+  First of all, the maintenance of the whois-parser component is the most time consuming task. Updating a parser may require from a few minutes to several hours, depending on how big are the changes. It also requires to generate the appropriate fixtures, and write the necessary tests. In the last years I noticed that more than once client updates were delayed because of pending parser changes. Separating the repositories and the release cycles will likely speedup future released of the client gem.
+
+  Moreover, the parser component takes a lot of space (due to all the files and fixtures). If you just need a Ruby whois client, loading the entire parser component is inefficient and a waste of time/CPU/resources.
+
+  Last but not least, in the last years the Whois client inspired several ports in different languages. Most of these ports were not interested in porting the parser as well. However, the parser was so tightly coupled with the client that it made the client code harder to read.
+
+- The definition files have been largely redesigned, in particular the TLD file. The definitions are now maintained using a set of CLI tools. The goal is to eventually extract the definition files into a separate, standalone repository that other WHOIS libraries can easily fetch.
+
+## Upgrade
+
+When upgrading, here's the most relevant changes to keep an eye on:
+
+- If you are using the Whois parser, install and require the `whois-parser` gem. The parser will automatically download the appropriate `whois` dependency.
+
+    ```ruby
+    require 'whois-parser'
+    ```
+
+  If you only need the client and you don't care about the parser, simply continue to require the `whois` gem directly.
+
+    ```ruby
+    require 'whois'
+    ```
+
+- `Whois::Server.definitions` no longer return the internal definitions. Definitions are no longer accessible directly, because their internal representation may change at any time. If you need to modify the definitions, use the public API.
+
+    ```ruby
+    Whois::Server.define(Whois::Server::TYPE_TLD, ...)
+    ```
+
+  You can still use `Whois::Server.definitions`, but it will return a copy of the internal definitions, and you have to specify which type of definitions you want to access.
+
+    ```ruby
+    Whois::Server.definitions(Whois::Server::TYPE_TLD)
+    ```
+
+- **The parser methods are no longer accessible directly within the response object.**
+
+  This is probably one of the most important changes, and it is explained in details at [weppos/whois-parser#5](https://github.com/weppos/whois-parser/pull/5).
+
+  In Whois 3, you can invoke a property method on a record object and the record will automatically route the method call to the underlying parser. If the property is not supported or defined in any of the parsers, then the method will return nil.
+
+  However, this behavior is often the cause of confusion and misunderstandings, especially for partially implemented parsers. Without to mention that the code required for this feature to work added an extra layer of complexity to the `Whois::Record` implementation.
+
+  Starting from Whois 4, the `Whois::Record` doesn't expose any parsing methods anymore. If you want to parse a record, you have to istantiate a parser manually. Of course, you also need to use the `whois-parser` library instead of `whois`.
+
+  Whois 3:
+
+    ```ruby
+    require 'whois-parser'
+
+    record = Whois.whois("example.it")
+    record.expires_on
+    ```
+
+  Whois 4:
+
+    ```ruby
+    require 'whois-parser'
+
+    record = Whois.whois("example.it")
+    parser = Whois::Parser.new(record)
+    parser.expires_on
+    ```
+
+  You can still use the convenient helper `record.parser` to initialize a parser:
+
+    ```ruby
+    require 'whois-parser'
+
+    record = Whois.whois("example.it")
+    record.parser.expires_on
+    ```
+
+  Also note that any parser method, such as `parser.expires_on`, will raise an error if the property is not implemented, as opposite to silently returning `nil` as it was in Whois 3.
+
+- **Parser extensions**
+
+  The Parser features available in Whois 3 has been packaged into several extensions. Some of them are loaded by default in Whois 4 when you require `whois-parser`, others not anymore. The reason is because although some of them may appear convenient (because it makes you write more code), it turned out that they made some assumptions that were often source of confusion.
+
+  Check the header of the [`whois/parser.rb`](https://github.com/weppos/whois-parser/blob/master/lib/whois/parser.rb) file to learn more about the purpose of each extension.
+
+  Requiring **all** the extensions will essentially force Whois 4 to work pretty much like Whois 3. This is not recommended, and you should not rely on those extensions to be there forever. Instead, you should write the code depending on what you actually need.
+
+  There is also an ENV variable you can set to rollback compatibility to Whois 3.
+
+    ```ruby
+    ENV["WHOISRB_4EXTENSIONS"] = 1
+    ```
+
+  Again, this flag exists only as temporary helper, and it should not become a permanent upgrade workaround.
+
+- **SafeRecord**
+
+  In the previous point I mentioned that you should write the code you need to customize the `Whois::Record` and extract information with the `Whois::Parser`. However, I omitted an important additional recommendation: avoid monkey patching the Whois::Record object, and instead prefer composition via delegation.
+
+  The SafeRecord is an example of a wrapper around a Record object, that expose a Whois 3 alike interface, without injecting the parser methods directly into the `Whois::Record` itself.
+
+  The advantages are:
+
+  - the code is more maintainable, as it is not tighlty coupled to the Whois::Record
+  - you don't monkey patch `Whois::Record` in your code, which is an object you don't have control of because it is packaged in a third party library (and can change)
+  - the library can easily be tested separately
+
+  In these 10 years of writing Ruby code, I've noticed an increasing attitude to monkey patch Ruby classes you don't control, instead of writing your own code and delegate to them. It looks like in several cases Ruby programmers are afraid of writing Ruby code. This results in very fragile code, where methods can easily conflict each other (especially between dependencies).
+
+  The `Whois::SafeRecord` is an alternative example of how you can restore Whois 3 behavior by using a custom object.
+
+    ```ruby
+    require 'whois/parser'
+    require 'whois/safe_record'
+
+    record = Whois.whois('example.com')
+    record.disclaimer
+    # => Whois::AttributeNotSupported
+
+    safe_record = Whois::SafeRecord.new(record)
+    safe_record.disclaimer
+    # => nil
+    ```
+
+  This is preferred over requiring the `whois/parser_extensions` or enabling v3 compatibility mode.
+
+  Please note that the parser extension is provided as example. It may be removed from future versions therefore, once again, you should write the code you need to access the parsed data.