Reorganized cookbooks dirs to be more self-explanatory

[patcon]

Related: applicationsonline/librarian#102

Proposal:

cookbooks/
├── 1-external
├── 2-overrides
└── 3-projects

Helpful? Suggestions for better naming? I used to use cookbooks-merge, because "overrides" are already a separate concept in Chef and I didn't want to overload the term, but at the time @darkoantic suggested cookbooks-overrides was better. Having second thoughts now.

[mparker17]

I like the proposed naming scheme (1-external, 2-overrides, 3-projects). Makes sense.

I agree with @darkoantic that "merge" is very difficult to understand.

[patcon]

So you don't see the fact that attributes exist at 3 levels (default/normal/override) as being an issue? People will open up a role to see how they work, and they're going to see "overrides" as one of the few properties. Seems confusing, but if no one else thinks so, we can leave it as "override". I'm not partial to "merge" as the alternative, for what it's worth, if anyone can think of a more novel term :)

/cc quick feedback from folks new to chef? @nerdcorenet, @mgifford, @sylus

[nerdcorenet]

In order to offer an opinion I need to understand first what is being suggested... Why three directories? What are they meant to be as full English descriptions? Once I can see that I might be able to offer some naming ideas. :)

[patcon]

Ah gotcha. This explanation is good practice for me:

• cookbooks are directories containing (among other things the sets of instructions ( recipes ) and variables ( attributes ) that are related to configuring a given piece of software or functionality, for instance java or nginx or php
• Attributes are part of each cookbook, and have 3 different levels of being set, in increasing precedence: default, normal, and override. This is needed because attributes can be set all over the place, in attribute files or in roles (a high-level Chef object) or even in other recipes.
• cookbooks tend to be placed in something informally called the "cookbooks directory", which is traditionally just named cookbooks/
• Chef can be told about multiple cookbooks directories, each at a specific level of precedence.
• If there are multiple cookbooks directories, Chef will kinda "merge in" together each directory structure, depending on the order of precedence you give each cookbooks directory in the Vagrantfile, so 1-cookbooks/ could be first, then 2-cookbooks/ might contain some directories that mirror the structure in 1-cookbooks/, but contain some files you want to override, and even some new files that never even existed in 1-cookbooks/

.
├── 1-cookbooks/
│   └── php/ [full cookbook]
│       ├── attributes/ ...
│       ├── recipes/ ...
│       ├── templates/ ...
│       ├── [etc...]
└── 2-cookbooks/
    └── php/ [containing just one file]
        └── templates/
            └── default/
                └── php.ini.erb

• We're currently using a tool called librarian to specify all the cookbooks we want to use, and it read a Cheffile and goes out and fetches all the cookbook from git repositories and from the official Chef community site, and creates the first cookbooks directory. The suggestion was to name this cookbooks directory 1-cookbooks-external, to indicate that it's the first layer in the cookbook merge and that these cookbooks come from external sources (brought in by librarian)
• The second directory is all our custom cookbooks that exist only in our project, and also all the overrides of the external cookbooks that librarian brought in, hence 2-cookbooks-merge or 2-cookbooks-override.
• The final cookbooks directory merged in is cookbooks that users might use to set up their specific drupal project. This is up to the user, and might include drush sql-syncs, or drush rsyncs, or drush site-install or just git clones. These are just kept separate for logical purposes, so that a user can keep track of any cookbooks that they implement for their own specific projects, hence 3-cookbooks-projects.

So was wondering, as a new person just getting to know Chef, what the most logical arrangement and naming might be, to help someone grapple with what each cookbooks directory does.

Now that I think about it, this might be the most logical, since we currently keeping overrides and custom cookbooks in the same cookbooks directory (cookbooks-override/)

cookbooks/
├── 1-librarian/ or 1-external/
├── 2-overrides
├── 3-custom
└── 4-projects

Oh my god. Wall of text. I suppose I just really want to structure this project in such a way that it's as approachable as possible, because it be quite complex and daunting :)

[darkoantic]

I can see what you are trying to achieve, but I don't think it is necessary to introduce the fourth directory. If you think that using the word overrides is incorrect because it could be confused with attribute, why not simply call it custom, as that is what the cookbooks inside of it are "The second directory is all our custom cookbooks that exist only in our project, and also all the overrides of the external cookbooks that librarian brought in." in which case the structure would look like

├── 1-librarian/ or 1-external/
├── 2-custom
└── 3-projects

[patcon]

👍 Thanks Darko :)
To clarify, the verbosity was a little misleading. I don't think it's a huge issue, but just treated it as a good exercise to flesh out a "Chef Quickstart" doc :)