Module/profile use of config/optional is apparently not documented

Yeah, we don't have documentation on config/optional apparently. ?!? sigh.

Only config/install is mentioned on
https://api.drupal.org/api/drupal/core!core.api.php/group/config_api/8
and
https://www.drupal.org/node/2120571

This is a nearly critical issue and must be fixed.

Summary update

Keep in mind that optional isn't working - for the moment - for profiles, see #2513604: Create default responsive image styles

This looks pretty good to me.... I wonder if the added paragraph should go a bit later though? It talks about dependencies, which are mentioned in the next bullet item.

Hm...

So actually, looking at
https://api.drupal.org/api/drupal/core!core.api.php/group/config_api/8
that bullet item that says:

Your module may also provide a few configuration items to be installed by default, by adding configuration files to the module's config/install directory; see Configuration YAML files above for more information.

is under Configuration Entities. That doesn't seem like the right place to add another bullet about config/optional.

I think what we should do instead is:

a) In the Configuration YAML Files section, add information about the config/install directory to the bullet item about "Defining the default configuration for a module". Right now it doesn't say there where to put these config items at all and it should.

b) Add a separate bullet item just after that about optional configuration in config/optional right after that (rather than blending it in as is done in the current patch). Mention that this is for configuration that has dependencies that are not explicit dependencies of your module, and that this config will be loaded when dependencies are met. [Actually... So if module A has config that depends on module B in its config/optional, and you install A and then later install B, will Drupal go back and find the B-dependent config in A's config/optional and install it then?] You might also reference the config entities section here, because that is where dependencies are mentioned.

c) Change the existing bullet item in the Config Entities section to say something like "Your module can provide default/optional configuration entities in YAML files, as described in @sec ..." and have that not mention the config/install directory explicitly.

Does that make sense?

Looking good! A few thoughts [note: reviewed #11 patch]:

1. +++ b/core/core.api.php
   @@ -232,10 +232,19 @@
     * - Defining the default configuration for a module, which is imported to the
   

   Should we also mention that themes and profiles can have config/install?

2. +++ b/core/core.api.php
   @@ -232,10 +232,19 @@
   + * - Defining optional configuration for a module. Optional configuration items
   

   I think themes can also have config/optional (and maybe profiles if that other issue gets fixed)?

3. +++ b/core/core.api.php
   @@ -232,10 +232,19 @@
   + *   are located in the config/optional sub-directory of the module. These are
   + *   not explicit dependencies of the module and may be installed at the end
   + *   of the installation cycle if all dependencies are met. For example, if
   

   Slight clarification on this sentence:

   These configuration items have dependencies that are not explicit dependencies of the module, so they are only installed if all dependencies are met.

4. +++ b/core/core.api.php
   @@ -232,10 +232,19 @@
   + *   a later stage. If the dependency is still not met at that point, the
   + *   configuration item will not be installed.
   

   Maybe add after this:

   If module B is installed sometime later, then module A's config/optional directory will be scanned at that time for newly met dependencies, and the configuration will be installed at that time.

   (or something like that...)

   I guess this will make the section a bit redundant? Maybe can be written to make it less redundant? But I think that point about returning later when B is installed is important to mention.

Looks great!

Just one small nitpick:

+++ b/core/core.api.php
@@ -231,11 +231,23 @@
+ * - Defining the default configuration for a module, theme or profile. It is

Needs comma after "theme" (we use serial commas by convention in the Drupal project).

And a suggestion for maybe slightly better wording:

+++ b/core/core.api.php
@@ -231,11 +231,23 @@
+ * - Defining the default configuration for a module, theme or profile. It is
+ *   imported to the active storage when the extension is enabled. ...

These first two sentences are a bit choppy. Maybe we could say:

Defining the default configuration for an extension (module, theme, or profile), which is imported to the active storage when the extension if enabled.

Looks good to me! Thanks!

Someone also needs to add similar information to
https://www.drupal.org/node/2120571
Want to do that too?

https://www.drupal.org/node/2120571 looks good to me, thanks! So all that remains is to get this patch committed.

Awesome, thanks both for catching this, and for working on these important docs that were missing!

Committed and pushed to 8.0.x. Thanks!