Add profile.api.php

MR opened.

Generated with the help of an LLM.

My bad, I just added the documentation for opt_out_install.
Is there another key that needs to be documented?

Unless I'm mistaken, the php key is supported for profiles.
ProfileExtensionList::$defaults sets it to \Drupal::MINIMUM_PHP, and ExtensionList::checkIncompatibility() checks $extension->info['php'] for all extension types including profiles.
That said, it is not documented anywhere else (modules, themes), so we can probably leave it out here too.

Hi @macsim,

1. I reviewed this and noticed that the `opt_out_install` key does not exist on `main` yet. As I understand it, it should probably only be documented after the other issue that introduces this key has been merged.

   I'm not sure what the best way to handle this here would be, but if this change is merged into `main` now, we would be documenting a key that does not yet exist in the codebase.

   I was updating my comment, so I ended up missing the comment above. You can ignore this.
   

2. There are also a few other documented keys that are not currently available. You can use the following command to check which keys are missing:

   grep -rhoE "profile(*info|->info)'?]?(['[a-z*]+'])+" core/ \
     --include='*.php' --include='*.inc' \
     | sed "s/.*info'?]?//; s/']['/./g; s/['//; s/']//" \
     | sort -u
   

3. I also noticed another issue with the examples.

   Both examples currently use:

   core_version_requirement: ^11
   

   However, `main` is currently on `12.0-dev`. Copying either example produces a profile that cannot be installed.

   `InfoParserDynamic` sets `core_incompatible`, the active profile is included in the module list by `ModuleExtensionList`, and `install_install_profile()` eventually reaches the check in `ModuleInstaller`. That check runs before the `$enable_dependencies` branch, so passing `FALSE` does not bypass it.

   Since nothing in the installer catches this incompatibility earlier, it eventually surfaces midway through the batch as a `MissingDependencyException`.

   Changing it to:

   core_version_requirement: ^12
   

   would fix the problem for now, but it would also mean updating the example for every new major version.

   Another option could be to use:

   core_version_requirement: >=11

   This would keep the example valid for Drupal 11, the current 12.0-dev branch, and future major versions without requiring an update each time. InfoParserInterface::parse() already uses >=9 as an example of this approach.

   It might also make sense to keep a single example rather than two, which would reduce the amount of documentation that could become stale over time.

Thanks for the regex @charlliequadros.
I added documentation for recipes and keep_profile missing keys.

For 3 core_version_requirement I would consider copying what module.api.php says about it

There's actually no example in module.api.php ; the only reference to core_version_requirement is in the hook_update_N documentation:

 * The numbers are normally composed of three parts:
 * - 1 or 2 digits for Drupal core compatibility (Drupal 8, 9, 10, etc.). This
 *   convention must be followed. If your module is compatible with multiple
 *   major versions (e.g., it has a core_version_requirement of '^8.8 || ^9'),
 *   use the lowest major core branch it is compatible with (8 in this example).
 * - 1 or 2 digits for your module's major release version. Examples:
 *   - For 8.x-1.* or 1.y.x (semantic versioning), use 1 or 01.
 *   - For 8.x-2.* or 2.y.x, use 2 or 02.
 *   - For 8.x-10.* or 10.y.x, use 10.
 *   - For core 8.0.x, use 0 or 00.
 *   - For core 8.1.x, use 1 or 01.
 *   - For core 8.10.x, use 10.

I am ok with both the core_version_requirement: ^12 and core_version_requirement: >=11 versions ; even if we choose the first one, it actually doesn't really need to be updated on each major version - that hook_update_N reference is still using a drupal 8 example and the documentation is still understandable.