On Wed, Aug 13, 2014 at 7:51 AM, Daniele Sluijters < daniele.sluijt...@gmail.com> wrote:
> What Nick, Henrik and Erik said. Rename the old tool, deprecate it and > remove it. `puppet doc` is the command that makes sense and that sensible > command should do sensible things. > > I kinda do like 'codex' though, it has a ring to it. > > -- > Daniele Sluijters > > > On Tuesday, 12 August 2014 23:52:39 UTC+2, Nick Fagerlund wrote: >> >> Well, something I've learned over the last four years is that cute names >> age a lot faster than you'd think. So I'm generally in favor of descriptive >> ones instead, at least when we're dealing with command -line tools. >> >> And unfortunately, "puppet doc" is pretty much the perfect name for it. >> :/ So, two things: >> >> 1. Can we consider renaming the old tool to puppet rdoc, as suggested >> earlier? It's always been janky; a rename might actually be a good signal >> to users that there's now something better. >> 2. If that's a no-go, we might want to use a temporary name for the new >> tool, one that shows it will eventually be called puppet doc. Maybe "puppet >> docplus" or something. Once we think we can get away with killing off the >> old-school puppet doc, I'd really like to reclaim its name for the improved >> tool. >> >> Anyway, if we can't use puppet doc: >> >> - puppet strings is all right, though I don't love it. (It's cute, but >> it's sort of domain-appropriate this time, so I could live with it.) >> - new suggestions: "puppet details" or "puppet codex." >> >> On Tuesday, August 12, 2014 10:33:04 AM UTC-7, Andy Parker wrote: >>> >>> On Tue, Aug 12, 2014 at 10:19 AM, Hailee Kenney <hai...@puppetlabs.com> >>> wrote: >>> >>>> >>>> puppet readme >>>> puppet guide >>>> puppet usage >>>> >>> >>> These three seem like they would be confused with "puppet help" too >>> easily >>> >>> >> >> I have the same problem with these three. >> > -- > You received this message because you are subscribed to the Google Groups > "Puppet Developers" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to puppet-dev+unsubscr...@googlegroups.com. > To view this discussion on the web visit > https://groups.google.com/d/msgid/puppet-dev/6aa1a498-9a57-4c72-bd5d-3279de6731b7%40googlegroups.com > <https://groups.google.com/d/msgid/puppet-dev/6aa1a498-9a57-4c72-bd5d-3279de6731b7%40googlegroups.com?utm_medium=email&utm_source=footer> > . > > For more options, visit https://groups.google.com/d/optout. > Alright, so based off the feedback on the naming and some discussion I think we've come to a reasonable solution (that definitely does not involve the word dox). Essentially we've decided to do what Henrik described above. To summarize, the end goal is to have a situation where when one uses the 'puppet doc' command, it will use the new tool and the old one will be gone completely.This will be a slow process though, since it will take some time to get the new tool to a place where it is functional enough to replace the current one. As a result, in the 3.x series, we will allow the current tool to be invoked using 'puppet rdoc', and when 'puppet doc' is called we will provide a warning explaining that it is being renamed, so that people have time to make the switch before Puppet 4. In Puppet 4, using the rdoc command will tell the user that it is deprecated and no longer supports manifest documentation. In addition it will direct them to the new tool (a module) which they can use instead (which will be called something else for a time, puppet string or puppet codex). Then eventually, when the new tool is functionally ready to be a full replacement for puppet rdoc, we will remove the old tool completely and 'puppet doc' will simply run the new tool which will ship with Puppet. -- Hailee Kenney hai...@puppetlabs.com Associate Developer, Puppet Labs *Join us at PuppetConf 2014 <http://www.puppetconf.com/>, September 20-24 in San Francisco* *Register by September 8th to take advantage of the Final Countdown <https://www.eventbrite.com/e/puppetconf-2014-tickets-7666774529?discount=FinalCountdown> * *—**save $149!* -- You received this message because you are subscribed to the Google Groups "Puppet Developers" group. To unsubscribe from this group and stop receiving emails from it, send an email to puppet-dev+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/puppet-dev/CALdYGa-D0WV3NH6TVSkt%2BsJV9C7FBRY%3DLYwyaXBbar%3Dt41wO9g%40mail.gmail.com. For more options, visit https://groups.google.com/d/optout.
