Revise Installation Documentation for Developers and Drupal 8.5

[tenken]

Issue

Continued usage of Sitefarm Seed (SFS) profile is a goal for the UCCSC 2019 conference to be hosted at UCSB. UCSB is attempting to leverage use of the SiteFarm Seed profile. After initial discussions with UCDavis staff and endevouring on our own to adopt the usage of SF within our project. Herein is an initial feedback of creating a basic project skeleton.

• The subprofile appears to work, but the resources and directions on how to create a subprofile of SFS was lacking and many hours were spent connecting dots that should have been easier given a functional README file.

• If the SFS project is accepting contributions[7][8], with advisement, UCSB is more than happy to contribute additional documentation for future projects hoping to use this Drupal project-based paradigm and to ease and increase UC wide adoption of SFS in future projects.

Pain Points Adopting SFS to a New Project

While Slack channels exist for communications on UC IT projects, ultimately project repositories should provide functional directions for employing a library within a project.

The template subprofile repository README[1][2] lists the directions to creating a subprofile as:

1. clone this github repo into your project. Rename files to fit your profile name.
2. run composer install
3. done, install drupal.

The above steps are inaccurate and will lead to installation failure. The main points of friction coming from these directions are:

• there is no mention of how composer adds drupal dependencies into the subprofile based project with the current composer.json[6] file. Should these dependencies be added to a project manually via composer require <DEP> for dependencies listed in sitefarm_seed/composer.json or should the project developer adapt the composer file to include a merge-plugin stanza and alter the distro template composer file to require the sitefarm_seed composer file.

• there is no mention of which version of the core patch[3] to be used for any Drupal Minor version should be applied. Over the lifetime of this issue there are 165 proposed patch files. There is mention in the SF issue queue of a valid version for Drupal 8.4.4 support[4], but we seek to start the project with Drupal 8.5. Through exhaustive research it was found that the Demo Umami SubProfile project[5] successfully uses a specific version of the listed patch.

Recommended Project Updates

As stewards of the SFS project it would be great if the maintainers contributors could:

1. Provide a set of directions providing example of composer usage for site installation dependencies where 2 profile folders must be examined by drupal to extract site dependencies upon site-install. This can be achieved in a project by being directed to include the following within the composer.json from the subprofile template repository:

  "merge-plugin": {
      "require": ["web/profiles/sitefarm_seed/composer.json"],
          "replace": false,
          "ignore-duplicates": true,
          "merge-extra": true,
          "merge-extra-deep": true,
          "merge-scripts": true
      },
  }

Also note there may other caveats to using composer in this fashion should the eventual subprofile support to land in Drupal core support only direct inheritance or other variants of inheritance, Composer has no knowledge of what dependencies will truly be enabled for a project; and thus composer may be over-greedy when building its' dependency matrix for a project using multiple subprofile(s) -- which could lead to developer friction attempting to use this subprofile development workflow within complex projects.

2. It's recommended the composer installer-paths be made consistent between the SFS profile and SFS subprofile project. In one repository they map to a web/ based directory tree -- in the other they do not:

• https://github.com/ucdavis/sitefarm_seed/blob/9a503e0b2d1d66dfca4084e06c5bbf72a5fb4ab5/composer.json#L90
• https://github.com/ucdavis/sitefarm-distro-template/blob/d6b254afd5c9579ebd70ce6c893081cfc780815c/composer.json#L76

3. It's recommended that the SFS project create Github Releases, or a wiki page where the composer patch file referenced for Profile Inheritance for Drupal Minor versions is pinned to a patchfile known to work for that version of Drupal. This resource would become unnecessary when the patch hits Core.

Thank you maintainers for your time and efforts on this project. The above constructive feedback is ment to aide future teams in adopting your project. If there are additional contributions we at UCSB can provide -- please let us know.

Footnotes

[1] https://github.com/ucdavis/SiteFarm-distro-template#get-started

[2] https://github.com/ucdavis/sitefarm_seed/blob/8.x-1.x/docs/creating_subprofile.md#create-a-sub-profile-of-sitefarm-seed

[3] https://www.drupal.org/project/drupal/issues/1356276

[4] https://github.com/ucdavis/sitefarm_seed/issues/184#issue-294859488

[5] https://cgit.drupalcode.org/demo_umami_subprofile/tree/drupal-org-core.make

[6] https://github.com/ucdavis/sitefarm-distro-template/blob/d6b254afd5c9579ebd70ce6c893081cfc780815c/composer.json

[7] https://github.com/ucdavis/sitefarm_seed/issues/55#issuecomment-302552278

[8] https://github.com/ucdavis/sitefarm_seed/issues/180

Edit:

• changed maintainer request to contributor request.

[mrkmiller]

@tenken thanks for the write-up on your experience. Just some quick thoughts on you points.

1. I'm not sure I'm correctly understanding the issue on this one. You shouldn't need to use the merge-plugin. The example is in the distro template https://github.com/ucdavis/sitefarm-distro-template/blob/master/composer.json. In fact, that whole template is the example. It is not meant to be used as is. You will want to modify it for your own needs. Composer also isn't concerned with what modules will be enabled in a profile. All it handles is what modules/packages need to be downloaded. Within your own profile you can decide what you want enabled in addition to what Sitefarm Seed enables. Originally the subprofile inheritance patch allowed a subprofile to disable modules from a parent profile, but I think they may have removed that feature.

2. You don't need to worry about the installer paths set in the Sitefarm Seed composer.json file. They aren't read by your parent distribution composer.json file (distro template). In fact they are being removed #188.

Your distro composer.json really controls everything. As far as composer is concerned the only thing coming from SiteFarm Seed is module/package dependencies and patches. Keep in mind that you can override any patch you like within your distro composer.json with patches-override. https://github.com/cweagans/composer-patches#ignoring-patches.

If you have been having installation failures as of late, it's due to the profile inheritance patch being out of date. This is being updated now, but also keep in mind that you can override that patch as you need if the main SiteFarm Seed repo isn't up to date. But yeah, it's frustrating if you're trying it out for the first time and don't know why it fails. That's the unfortunate side of relying an a significant patch. Ideally you shouldn't need to worry about what patch works where. Ideally Sitefarm Seed should take care of that for you, but it simply hasn't been updated in a while. :(

Any pull requests to the docs https://github.com/ucdavis/sitefarm_seed/tree/8.x-1.x/docs are more than welcome.

[tenken]

Ah, I know better understand the issue now.

Because the sitefarm_seed repository was not updated anytime recently to support D8.5. I Forked the repo on github and copied it down locally to a repo hosted within UCSB. I then updated the sitefarm_seed composer.json file to be 8.5 compatible.

I then updated the distro composer file to reference the ucsb sitefarm_seed repository which brings in sitefarm profile folder into my project.

I'm still confused a little on why you think (1) isn't an issue. The directions on how to start working on a sub profile based project are here: https://github.com/ucdavis/SiteFarm-distro-template#get-started

This line from the distro template:

https://github.com/ucdavis/sitefarm-distro-template/blob/master/composer.json#L44

Does not tell my project to include the dependencies of the sitefarm seed profile into my project. It just brings the sitefarm_seed profile folder as a vendor resource into my project files and places them at:

            "web/profiles/{$name}": [
                "type:drupal-profile"
            ],

In order to automatically fetch this profiles dependencies and allow a simple Getting Started 3-step-process to working on a project -- you would have to use a tool like merge-plugin to have Composer get the additional dependencies required by the parent profile !? ... wouldn't you?

If you do then the Getting Started directions would work as advertised:

cd <project dir>
composer install
cd web
drush site-install my_custom_profile <typical options list>

Otherwise these directions Composer will download and install the SiteFarm install profile. You can then install it like you would any other Drupal site. may as well read:

manually goto your drupal project directory and require every dependency of the sitefarm_seed profile so that the installation can complete for your sub profile of sitefarm_seed.

Is this more clear? Am I incorrect in my analysis above someplace? I'm just trying to help other adopters have an easier path to initial development when using this specific project workflow.

Thanks for your time.

[mrkmiller]

This line from the distro template:

https://github.com/ucdavis/sitefarm-distro-template/blob/master/composer.json#L44

This is all that is needed for composer to parse the dependencies within SiteFarm Seed. It will place the sitefarm_seed profile into the /profiles directory and then place all of the modules into /modules/contrib/.

So if I clone the distro template, and run composer install it will create the following:

If I then go to the web directory and do:

drush site-install sitefarm_subprofile --account-name=johndoe --account-pass=test --site-name="SiteFarm"

It will install a new Drupal site using the sample sitefarm_subprofile sub profile.

That should be all that is needed.