From 59cd5338d422adc021e07d78f3b6e90ae44f54a2 Mon Sep 17 00:00:00 2001 From: Mike Dalessio Date: Wed, 18 Aug 2021 20:12:41 -0400 Subject: [PATCH] update CHANGELOG --- CHANGELOG.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1e992254fb..7e79eb3512 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,61 @@ Nokogiri follows [Semantic Versioning](https://semver.org/), please see the [REA * [CRuby] If a cycle is introduced when reparenting a node (i.e., the node becomes its own ancestor), a `RuntimeError` is raised. libxml2 does no checking for this, which means cycles would otherwise result in infinite loops on subsequent operations. (Note: JRuby/Xerces already does this.) [[#1912](https://github.com/sparklemotion/nokogiri/issues/1912)] +## 1.12.4 / unreleased + +### Notable fix: Namespace inheritance + +Namespace behavior when reparenting nodes has historically been poorly specified and the behavior +diverged between CRuby and JRuby. As a result, making this behavior consistent in v1.12.0 introduced +a breaking change. + +This patch release reverts the Builder behavior present in v1.12.0..v1.12.3 but keeps the Document +behavior. This release also introduces a Document attribute to allow affected users to easily change +this behavior for their legacy code without invasive changes. + + +#### Compensating Feature in XML::Document + +This release of Nokogiri introduces a new `Document` boolean attribute, `namespace_inheritance`, +which controls whether children should inherit a namespace when they are reparented. +`Nokogiri::XML:Document` defaults this attribute to `false` meaning "do not inherit," thereby making +explicit the behavior change introduced in v1.12.0. + +CRuby users who desire the pre-v1.12.0 behavior may set `document.namespace_inheritance = true` before +reparenting nodes. + +See https://nokogiri.org/rdoc/Nokogiri/XML/Document.html#namespace_inheritance-instance_method for +example usage. + + +#### Fix for XML::Builder + +However, recognizing that we want `Builder`-created children to inherit namespaces, Builder now will +set `namespace_inheritance=true` on the underlying document for both JRuby and CRuby. This means that, on CRuby, the pre-v1.12.0 behavior is restored. + +Users who want to turn this behavior off may pass a keyword argument to the Builder constructor like +so: + +``` ruby +Nokogiri::XML::Builder.new(namespace_inheritance: false) +``` + +See https://nokogiri.org/rdoc/Nokogiri/XML/Builder.html#label-Namespace+inheritance for example +usage. + + +#### Downstream gem maintainers + +Note that any downstream gems may want to specifically omit Nokogiri v1.12.0--v1.12.3 from their dependency specification if they rely on child namespace inheritance: + +``` ruby +Gem::Specification.new do |gem| + # ... + gem.add_runtime_dependency 'nokogiri', '!=1.12.3', '!=1.12.2', '!=1.12.1', '!=1.12.0' + # ... +end +``` + ### Fixed * [JRuby] Fix NPE in Schema parsing when an imported resource doesn't have a `systemId`. [[#2296](https://github.com/sparklemotion/nokogiri/issues/2296)] (Thanks, [@pepijnve](https://github.com/pepijnve)!)