Document the relations between packages, projects, extensions, modules, themes, and profiles

Thanks for creating this! 😊👍

Crediting @yash.rode.

As I think about this, I realize I'd like some input from Wim before we continue.

Why? Because project name and extension name are two different things. We can map packages to projects, which sometimes correspond to extensions, but not always. A project can contain multiple extensions. So I'm wondering if we even want to make this change, really.

Because project name and extension name are two different things.

We can map packages to projects,

Ah, no, it can't: d.o-served packages are named drupal/PROJECT_NAME and map to https://www.drupal.org/project/PROJECT_NAME 😬

which sometimes correspond to extensions, but not always. A project can contain multiple extensions. So I'm wondering if we even want to make this change, really.

You're right.

Mea culpa. 😢

Can we then rescope this to add crystal clear documentation to package_manager.api.php to forever document the 1:1, 1:0|1, 1:N and N:1 relations between package, project, extension, module, theme and profile? 🙏

Wim Leers → closed merge request !846

MR closed, issue summary updated. We need a new MR here. I'll take this on, so @phenaproxima can review 😊

First draft pushed up.

Reviewed and...well, I have to be very honest: I think the proposed wording is over-explaining it.

I think that all we really need to say is this: Composer packages are the main thing we're dealing with. They can contain any number of projects (I know, in practice they only contain one, but in theory they could contain more); a "project" is a thing with a page on d.o (and is sometimes colloquially referred to as a "module" or "theme"). Each project, in turn, can contain any number of extensions (meaning modules, profiles, and themes).

This stuff is already complicated, so IMHO we want to explain the bare minimum to prevent information overload.

I don't think the current MR explains it well and I don't think the suggestion in #15 really gives enough info to be helpful.

To me this really feels like it should be drupal.org documentation page rather than something that is in package_manager.api.php. Because even if you don't use package manager at all these concepts still apply and I don't think they are generally well understood.

So I would be in favor of documentation page on drupal.org that is not package_manager specific and just linking to that page in package_manager.api.php

I'm fine with moving this out of Package Manager into core.api.php or something else like that that is very general/broad.

But … this is the very first time that anything in Drupal core truly needs to care about these connections. I personally got very confused while working on 📌 Create a PreApply validator that prevents Drupal projects from being removed if they are enabled Fixed . And I've been in Drupal for >15 years.

Anything that is so thoroughly confusing should be documented IMHO.

I like where @phenaproxima was going, but @tedbow thinks it's not helpful enough. So … @tedbow, could you propose an alternative? 🙏

(Discussed in detail during yesterday's meeting, @tedbow is indeed going to update the MR.)