add future comments

Signed-off-by: Lamont Granquist <lamont@scriptkiddie.org>

2 files changed, 20 insertions, 0 deletions

diff --git a/lib/chef/version/platform.rb b/lib/chef/version/platform.rb
index 07b1a17b11..6d8f4192fe 100644
--- a/lib/chef/version/platform.rb
+++ b/lib/chef/version/platform.rb
@@ -16,6 +16,24 @@
 
 require "chef/version_class"
 
+# NOTE: this is fairly badly broken for its purpose and should not be used
+#       unless it gets fixed.
+
+# this strictly wants x, x.y, or x.y.z version constraints in the target and
+# will fail hard if it does not match.  the semantics that we need here is that
+# it must always do the best job that it can do and consume as much of the
+# offered version as it can.  since we accept arbitrarily parsed strings into
+# node[:platform_version] out of dozens or potentially hundreds of operating
+# systems this parsing code needs to be fixed to never raise.  the Gem::Version
+# class is a better model, and in fact it might be a substantially better approach
+# to base this class on Gem::Version and then do pre-mangling of things like windows
+# version strings via e.g. `.gsub(/R/, '.')`.  the raising behavior of this parser
+# however, breaks the ProviderResolver in a not just buggy but a "completely unfit
+# for purpose" way.
+#
+# TL;DR: MUST follow the second part of "Be conservative in what you send,
+# be liberal in what you accept"
+#
 class Chef
   class Version
     class Platform < Chef::Version
diff --git a/lib/chef/version_constraint/platform.rb b/lib/chef/version_constraint/platform.rb
index 29f4678bb5..e39da194c6 100644
--- a/lib/chef/version_constraint/platform.rb
+++ b/lib/chef/version_constraint/platform.rb
@@ -16,6 +16,8 @@
 require "chef/version_constraint"
 require "chef/version/platform"
 
+# NOTE: this is fairly badly broken for its purpose and should not be used
+#       unless it gets fixed.  see chef/version/platform.
 class Chef
   class VersionConstraint
     class Platform < Chef::VersionConstraint