Create a Getting_started.md in the docs

I have started a basic outline and rough draft.

Per @andypost

Suggestion to add - "documentation could start use help topics as they been merged to help and its standard helpful for task-oriented recipes" refer to the following guide:
/docs/develop/managing-a-drupalorg-theme-module-or-distribution-project/documenting-your-project/help-topic-standards

Added Configuring Drupal to Apply Recipes.md to the repo about how to set up your site project for recipes.

Uploading it as a file also. Never sure I am doing Gitlab right.

I ran through this document and was able to set up a Drupal project with recipe support.

One helpful thing I discovered is that you don't have to edit composer.json manually at all. You can do it all with commands. Admittedly, some of those commands are more complicated than others...but you can still just script them. (Or, indeed, we could provide a script to do that -- and we should!)

Here's the sequence:

composer config allow-plugins.cweagans/composer-patches true
composer require cweagans/composer-patches
composer config extra.patches --merge --json '{"drupal/core": {"Allow recipes to be applied": "https://git.drupalcode.org/project/distributions_recipes/-/raw/patch/recipe.patch"}}'
composer update drupal/core
composer config allow-plugins.oomphinc/composer-installers-extender
composer config extra.installer-types --merge --json '["drupal-recipe"]'
composer config extra.installer-paths --merge --json '{"web/recipes/contrib/{$name}": ["type:drupal-recipe"]}'
composer require oomphinc/composer-installers-extender

Thanks for #15! That was simpler/faster than going through the entire .md file (which I did first).

I tried this on 10.1.x (HEAD is currently 6a68463ce9a5a540ef25e1c6f5a26420a75483f0) and after a fresh install:

$ vendor/bin/drush si --account-name=root --account-pass=root --site-name=LiveDemoWhatCouldGoWrong --yes
 You are about to:
 * DROP all tables in your 'core' database.

 // Do you want to continue?: yes.                                                                                    

 [notice] Starting Drupal installation. This takes a while.
 [notice] Performed install task: install_select_language
 [notice] Performed install task: install_select_profile
 [notice] Performed install task: install_load_profile
 [notice] Performed install task: install_verify_requirements
 [notice] Performed install task: install_verify_database_ready
 [notice] Performed install task: install_base_system
 [notice] Performed install task: install_bootstrap_full
 [notice] Performed install task: install_profile_modules
 [notice] Performed install task: install_profile_themes
 [notice] Performed install task: install_install_profile
 [notice] Performed install task: install_configure_form
 [notice] Performed install task: install_finished
 [success] Installation complete.

I did

composer require kanopi/gin-admin-experience

(per the .md file 👍)

It failed like this:

$ php core/scripts/drupal recipe web/recipes/contrib/gin-admin-experience

In SimpleConfigUpdate.php line 47:
                                                                     
  Config block.block.gin_admin does not exist so can not be updated  
                                                                     

recipe <path>

Is this expected? Is this 10.1.x-specific? For now, assuming it's harmless, so just logging in to my fresh site and:

Drupal\Component\Plugin\Exception\PluginException: Plugin (admin_toolbar_tools.extra_links:node.add.article) instance class "Drupal\admin_toolbar_tools\Plugin\Menu\MenuLinkEntity" does not exist. in Drupal\Component\Plugin\Factory\DefaultFactory::getPluginClass() (line 97 of core/lib/Drupal/Component/Plugin/Factory/DefaultFactory.php).

A quick drush cr later and it seems to have worked 👍

It seems like on of the most obvious low-hanging fruits of the current state of this project is to automatically do a cache rebuild? 😅🤓

(Also why does kanopi/gin-admin-experience not change the default admin theme?! 🥸 That seems to be the whole point of this recipe? 😅 After I changed that manually at /admin/appearance, it did what I expected it to! 👍)

Made a Docksal script that does the above. Will have to convert it to a regular bash script.

#!/usr/bin/env bash

## One time Composer configuration for Drupal recipes.
##
## Usage: fin recipe-configure

# Abort if anything fails
set -e

#-------------------------- Helper functions ------------------------------

green='\033[0;32m'
yellow='\033[1;33m'
NC='\033[0m'

divider='===================================================\n'
party='\xF0\x9F\x8E\x88 \xF0\x9F\x8E\x89 \xF0\x9F\x8E\x8A'
reverseparty='\xF0\x9F\x8E\x8A \xF0\x9F\x8E\x89 \xF0\x9F\x8E\x88'
require_command='fin composer require org/recipe-name'
apply_command='fin recipe-apply recipe-name'
unpack_command='fin recipe-unpack org/recipe-name'

#-------------------------- Execution ------------------------------

# Configure Composer Patches.
fin composer config allow-plugins.cweagans/composer-patches true
fin composer require cweagans/composer-patches

# Add Drupal core patch for recipes to composer.json and update core.
composer config extra.patches --merge --json '{"drupal/core": {"Allow recipes to be applied": "https://git.drupalcode.org/project/distributions_recipes/-/raw/patch/recipe.patch"}}'
fin composer update drupal/core

# Configure the location recipes go when required.
fin composer config allow-plugins.oomphinc/composer-installers-extender
fin composer config extra.installer-types --merge --json '["drupal-recipe"]'
fin composer config extra.installer-paths --merge --json '{"web/recipes/contrib/{$name}": ["type:drupal-recipe"]}'
fin composer require oomphinc/composer-installers-extender

# Requires Drupal Recipe Unpack.
fin composer config allow-plugins.ewcomposer/unpack true
fin composer config repo.recipe-unpack vcs https://gitlab.ewdev.ca/yonas.legesse/drupal-recipe-unpack.git
fin composer require ewcomposer/unpack:1.x-dev@dev

# Complete
echo -e "\n${yellow} ${party} Your project is now ready to apply recipes! ${reverseparty}${NC}"
echo -e "Run ${yellow}${require_command}${NC} to require a recipe."
echo -e "Run ${yellow}${apply_command}${NC} to apply a recipe."
echo -e "Run ${yellow}${unpack_command}${NC} to unpack the recipe's dependencies to the project's composer.json"
echo -e "Be sure to export configuration after recipe application to capture its config in your site."
echo -e "${green}${divider}${NC}"

@Wim Leers. It appears that your recipe application failed at the block, and it never got to the config:actions section to set the admin theme.

Drush si defaults to the standard profile, which has more opinions. Could you try the following to start from minimal?

$ vendor/bin/drush si minimal --account-name=root --account-pass=root --site-name=LiveDemoWhatCouldGoWrong --yes

Reinstalled on 10.2 using #3399825: Create patch for 10.2.x → .

First

composer require kanopi/gin-admin-experience

then

1. vendor/bin/drush si --account-name=root --account-pass=root --site-name=LiveDemoWhatCouldGoWrong --yes
   php core/scripts/drupal recipe web/recipes/contrib/gin-admin-experience
   

   Same error as in #16:

   $ php core/scripts/drupal recipe web/recipes/contrib/gin-admin-experience
   
   In SimpleConfigUpdate.php line 47:
                                                                        
     Config block.block.gin_admin does not exist so can not be updated  
                                                                        
   
   recipe <path>
   

2. Then, following the advice of #18:
   

   $ vendor/bin/drush si minimal --account-name=root --account-pass=root --site-name=LiveDemoWhatCouldGoWrong --yes
   $ php core/scripts/drupal recipe web/recipes/contrib/gin-admin-experience
   
                                                                                                                           
    [OK] Gin Admin Experience applied successfully                                                                         
   

👍 Thank you!

However … this means that Recipes are failing to live up to their promise? 🫣 I want to start from Standard so that I get Olivero, not Stark. Then I want Gin. Isn't that a reasonable expectation? 🤔

I think something in the installation of themes/modules is not working when starting from Standard, because vendor/bin/drush cget block.block.gin_admin tells me the block does not exist in either case (Standard/Minimal). Only on Minimal does applying the recipe work.

Debugged this.

1. When installing gin, hook_themes_installed() is invoked.
2. block_theme_initialize() makes a new theme get the same blocks as the current default theme (system.theme:default).
3. The current default theme in Minimal is stark.
4. stark has a stark_admin block, defined by core/profiles/minimal/config/install/block.block.stark_admin.yml
5. 👆 that block is defined in the Minimal install profile, not in Stark itself!

Gin Admin Experience can only ever work successfully if and only if Minimal was installed! It will fail on every other theme, because it's tightly coupled to the exact set of blocks that is created for Stark in Minimal 😅 — at least in its current incarnation at https://github.com/kanopi/gin-admin-experience/blob/f5129ea3596b3ebbc5c4....

Just a reminder, as of 10.2 core instead of .md files it is more handy to ship help topics, ref https://www.drupal.org/node/3382015 →

Guide is https://www.drupal.org/docs/develop/managing-a-drupalorg-theme-module-or... →

We discussed in slack and found that there is a good defined precedent created by the User Guide project.

If we build out our docs the same as https://git.drupalcode.org/project/user_guide/-/tree/10.0.x, then we can use a manual technique to publish to Drupal.org, and then when we’re in core it’ll be easy to add the docs to the user guide.

Help Topics can be built out in a future phase.

Taking myself off as assigned so someone else can hop in.

Adding follow up:

Update our documentation to use AsciiDoc markdown format
https://www.drupal.org/project/distributions_recipes/issues/3409318 →

To address the comment in #20, I have reworked the kanopi/gin-admin-experience recipe with heavy use of ensure_exists to allow the recipe to be installed on Minimal and Standard Profiles, and Stark, Olivero, and Claro themes.

This was the last blocker to getting this merged. I will work on merging the getting started doc into the code base now.

Adding credits.

Merged in 1.0.x.

Nice, great work, @thejimbirch! 👏🙏

Automatically closed - issue fixed for 2 weeks with no activity.

thejimbirch → closed merge request !51