Warn instead of erroring when generating a cookbook with a hyphen in the name.

[TonyLovesDevOps]

Changes the error message introduced in #915 to a warning, shown when a user is generating a cookbook with a hyphen in the name.

[mwrock]

this doesn't change history so we'd keep the 0.16 docs alone.

[TonyLovesDevOps]

Do you mean, leave these messages in and add a new entry for switching to a warning?

[mwrock]

when we do a release, we "auto" generate the changelog and releasenotes based on GH commits. So if this were merged, it would show up in 0.17.

[mwrock]

Basically you can leave these 2 files alone.

[mwrock]

With the comments above in mind, I like this.

[mwrock]

👍

[charlesjohnson]

The change to disallow hyphens in the generator came about as part of a larger effort to remediate a recurring pain felt by many different people. Copy/pasting from the internal issue tracker to provide context:

User Story

As a creator of custom resources with the Chef DSL, I should be able to reference those custom resources by the default resource name, even if the cookbook name has hyphens, so that I can reference those custom resources by a predictable name.

Background and cause

If a person has a cookbook with a dash in its name, e.g. fizz-buzz, and a resource file e.g. fizz-bizz/resources/quux.rb, and so tries to use the resource as described in the Custom Resources docs:

fizz-bizz_quux 'xyz' do
  # ...
end

This will fail because hyphens aren't allowed in Ruby identifier names or, more specifically, because the Ruby parser interprets fizz-bizz_quux as three separate tokens: The identifier (variable or method name) fizz, the - (minus) operator, and the identifier bizz_quux. This happens in the parsing phase, before any code is run, so there's no way to change this behavior short of, say, writing our own Ruby parser.

History and workaround

The first found recorded report of this issue was was in reported in Dec. 2011, and a workaround was implemented: When compiling a resource, hyphens and other non-alphanumeric characters are replaced by underscores, so the author need only make a small adjustment:

fizz_bizz_quux 'xyz' do
  # ...
end

This works today.

Nevertheless, this issue is still reported by a (rightfully) confused person about once a year (1, 2, 3). These people are usually given the above advice (use underscores where your cookbook name has hyphens), which solves their immediate problem.

The bigger picture

The issue keeps coming up because we only ever explain it to those who get bitten. The only place our docs mention restrictions for cookbook names is in the Chef Style Guide. Until recently, Chef even use hyphens in cookbook names in some of our official tutorials and many of our own cookbooks.

Remediation

The solution decided upon was to educate and, when possible, guide cookbook authors. To that end, the following changes were made, in different areas:

Docs changes:

• Update custom resources documentation to contain information about this issue.
• Update Chef docs to discourage use of hyphenated cookbook names.

Learnchef changes:

• Work with Learnchef maintainers to replacing hyphenated cookbook names in the curriculum with underscores.

Generator changes:

• Update cookbook generator to disallow hyphens, suggest underscores instead.

Conclusion

While I don't believe it's necessary to change the Chef specification to fully disallow hyphens in cookbook names, I do believe that disallowing the use of hyphens in the generator is a useful guard that will reduce long-term confusion. In addition, because chef generate cookbook creates a fair amount of scroll, any warning is likely to be visually lost in the boilerplate.

As such, while I appreciate the contribution very much, I am hard 👎 on this change.

[agh]

What would it take to move ChefDK over to a versioning model, similar to Chef itself?

https://github.com/chef/chef-rfc/blob/master/rfc047-release-process.md

I appreciate the background above, but I think we could have done better in three respects -

• This additional detail was not present in the Pull Request which changed the behaviour, and there's obviously valuable context here from your internal issue tracker. It is therefore super hard for the community to judge a change, "Why is this important?".
• It wasn't made blindingly obvious in the release information (CHANGELOG) that behaviour changed in a way which could "break" people using chef generate. I use the term break because if you have 100+ cookbooks using hyphens, that's your workflow, this change mandates that I immediately change to stop using hyphens.
• Its easy to believe ChefDK is conforming to SemVer (i.e. 0.16.x matches major, minor, patch) whereas this cannot be the case. If this software were to conform to RFC47 then that might have served to be an additional hint that something had changed behaviourally?

I filed my original concern from #915 as a support request and was largely fobbed off, and maybe this Pull Request isn't the right place to solve this either, what is the correct forum?

[TonyLovesDevOps]

@charlesjohnson thank you for the background on this. I understand, and am sympathetic to the situation, and support making it easier for you guys to handle

The change in behavior is reasonable in a vacuum.

However, as @agh mentions, where it's hurting us is that we internally have years of documentation, existing cookbooks, and automation code around naming practices that expect (and in many cases, require) hyphenated cookbook names to adhere to our internal specifications.

So we're in a situation now where we must immediately change all of these things, re-educate out internal customers, rename existing cookbooks along with the concomitant role/doc/node changes, touching every node in our fleet with the best case outcome being 'nothing goes wrong'.

Finally, the idea of putting in this level of effort to avoid having a "confused person about once a year" sticks in my craw. <-- I'm joking. A little bit.

[docwhat]

I would have rather preferred that chef-client required the resource name be always specified instead of trying to infer it from the cookbook name.

[jtimberman]

I'm also not a fan of the change to make chef generate bail out when a cookbook name has a dash/hyphen in it. Chef has always given users enough rope to footgun themselves. Certainly a user can create a cookbook with a dash manually, but I think it would be good to have this stay available via chef generate. Ideas to accomplish this:

• remove the hard failure/exit as this PR suggests
• allow a custom generator cookbook to handle this
• create a command-line option that lets the user override this behavior
• prompt the user saying "This is unwise" and require input

There's varying degrees of convenience, and I get the pain and frustration we've felt in things like custom resources not allowing dashes in the cookbook name, and other potential hazards of having a dash in the name. However, precedent is established through years of people and teams establishing practices of using dashes in the name, and breaking their workflows feels like a bad UX to me.

[charlesjohnson]

This is still open as a place to discuss the options.

Again, to be very clear: Cookbooks with hyphenated names are allowed in Chef. There is no plan to disallow the usage of cookbooks with hyphenated names. People rely on cookbooks created with this convention, it has been an allowed practice for as long as there's been Chef, and this change would break the world. There is no plan to disallow the usage of cookbooks with hyphenated names.

We hear loud and clear that this generator limitation feels too strict in its current implementation. As @jtimberman outlined above, we're looking at ways of achieving the goal of discouraging the use of hyphens in the cookbook generator without disabling them completely.

Unfortunately, it's unlikely that the change to loosen this restriction will land in the ChefDK slated for release on August 17th, but we'll aim for September.

[TheLinuxNinja]

I just hit the bug in 'chef generate cookbook' where instead of actually generating the cookbook, it bombs out complaining about completely legal dashes in the cookbook name. The solution being to change the generate cookbook name to have underscores instead of dashes in order to get it to work, then manually renaming the directory and editing all the files it creates to change the underscores back to dashes is a ridiculous exercise. I whole-heartedly agree with the above comments that this heavy-handed method of getting the occasional annually confused individual to not footgun himself is breaking existing workflows, like ours.

There is too much history around dashes in cookbook names. Let's find another way, please.

[charlesjohnson]

Just gonna copy/paste myself again:

Again, to be very clear: Cookbooks with hyphenated names are allowed in Chef. There is no plan to disallow the usage of cookbooks with hyphenated names. People rely on cookbooks created with this convention, it has been an allowed practice for as long as there's been Chef, and this change would break the world. There is no plan to disallow the usage of cookbooks with hyphenated names.

We hear loud and clear that this generator limitation feels too strict in its current implementation. As @jtimberman outlined above, we're looking at ways of achieving the goal of discouraging the use of hyphens in the cookbook generator without disabling them completely.

[lamont-granquist]

👍

[jkeiser]

👍

[jkeiser]

We're electing to make this a warning now because we feel like that's the best way forward at the moment. @charlesjohnson is not around to defend the new prompt UX proposed, however, so this may show back up as a prompt in the future. We'll consider it carefully when we do. In the meantime, we place a higher priority on making it possible for users to use chef generate cookbook in their workflow again.