[chef-dev] Re: Re: Re: Accepted RFCs for October 15th

[Mike < >]

Thanks Lamont!

I'm not specifically calling out rest-client removal as a point of discussion, since it's not part of the chef code "public API" - it wasn't being used in the codebase, any project that explicitly needs it should be specifying that, agreed it can be removed with no point release, etc.

But for things which we _do_ have current code in place that _is_ part of the public API of chef-client, such as the feature that was referenced (not rest-client), we have the ability to add a deprecation notice (I believe there's even built-in methods in the Chef codebase, no?) so anyone looking at logs can see them and act.

> SemVer mostly applies to WebAPIs or library calls where you can look at your inputs and notify the user that they're using the deprecated API.  In the case of chef-client we just instance_eval random ruby code and expect you to be somewhat restrained in the size of the footgun that you build. 

I kind of object to this notion - SemVer is a specification in which software - packaged, library or API call - can opt-in to adhere to or not, and I was under some impression that Chef was attempting to follow Semantic Versioning practices for software releases. If that's not the case, please let the rest of us know.

> We can't possibly follow SemVer to the letter in every case.

No, but we can definitely try. And if we can set a pattern in which we try hard to adhere before finding a reason to not adhere, it'll probably save us heartache later on.

Best,

-M

On Thu, Oct 16, 2014 at 8:48 PM, Lamont Granquist < " target="_blank"> > wrote:

On Thu Oct 16 11:09:24 2014, Noah Kantrowitz wrote:

On Oct 16, 2014, at 7:34 AM, Mike < " target="_blank"> > wrote:

Thanks Noah for the summaries!

## RFC 26: Remove HTTP Config Files

https://github.com/opscode/chef-rfc/blob/master/rfc026-remove-http-config-files.md

This deprecates a relatively unknown feature whereby chef-client can download its configuration directly from an HTTP server. Given how little this feature is believed to be used, an aggressive deprecation schedule will be used such that the feature will throw a warning in future Chef 11 versions and be entirely removed in Chef 12.

Sorry I missed the discussion on this particular RFC on chef-rfc repo, and am unsure how to continue discussion on an already-accepted RFC - is that detailed somewhere?

One point I'd like to ask about here is the "warning and deprecation" model - it appears that this is going to be removed completely in Chef 12, and a deprecation warning will be added to Chef 11.
I've seen mention that there may not be any further Chef 11.x releases until Chef 12 is out, which actually makes the deprecation warning a little "too late" for anyone looking to upgrade and retain functionality.

Now, I don't think this is The Most Important Feature that is likely to cause massive breakage for users, but it does surface the need to describe a clear deprecation methodology for anything that is going to be changed significantly in Chef 12 and onwards.

RFC015 [1] does a good job of defining a few of changes that are not backwards compatible, but I don't believe there's any mention of adding deprecation warnings in current Chef 11 for users of these features/code paths.

 From SemVer doc [2]:

| How should I handle deprecating functionality?
| Deprecating existing functionality is a normal part of software development and is often required to make forward progress. When you deprecate part of your public API, you should do two things: (1) update your documentation to let users know about the change, (2) issue a new minor release with the deprecation in place. Before you completely remove the functionality in a new major release there should be at least one minor release that contains the deprecation so that users can smoothly transition to the new API.

So it seems that the first part about updating documentation is happening now, as well as will most likely be in the Chef 12 release notes, but the second part about issuing a minor release of Chef 11 with deprecation warnings (and any cookbooks that have deprecated code) should happen before the Chef 12 release.

This is why I specifically called it out as an aggressive removal. Given how few people knew this feature existed, and how easy the workaround is, the conclusion was that going faster than SemVer recommends was okay in this instance. The resulting cleanup in the config code is substantial enough to warrant it in my opinion. No code has been merged yet though, so if you think this is a mistake I would start a new ML thread (just for visibility) :)

--Noah

Since we're going to be covering Chef 11 with security and critical bugfix releases there will still be a support path for Chef 11 users who hit deprecated features in Chef 12 and can't upgrade right away.

We also have any deprecated features in Chef 12 for which there will be no warning.  We removed the dependency on rest-client for example because no code in the chef-client codebase used rest-client any more and it was causing problems.  There is no deprecation warning and likely will never be a deprecation warning because we'd need to somehow monkeypatch rest-client to catch the use of it without an explicit requires line outside of chef-client -- that probably can in theory be done (nearly anything can be done in ruby with an ugly enough monkeypatch), but is incredibly fussy and would waste someone's time that could be better spent fixing bugs.  So the deprecation warning is going out in the CHANGELOG and RELEASE_NOTES and I'm again mentioning it here.  So, there are a few cookbooks that will not work out of the box on Chef 12 without a patch and they will not have any deprecation warnings (ever) in Chef 11.

SemVer mostly applies to WebAPIs or library calls where you can look at your inputs and notify the user that they're using the deprecated API.  In the case of chef-client we just instance_eval random ruby code and expect you to be somewhat restrained in the size of the footgun that you build.  We can't possibly follow SemVer to the letter in every case.