Define the Package Manager API (package_manager.api.php is outdated)

Adjusting credits. The patch in #4 didn't seem to add anything useful so I don't think it should get credit.

re #3328978: Do we want to Throw an Exception if a git directory unknown to composer is added in Stage? we should clearly document package manager expects the stage to be only operated on via composer stager, i.e. if you run other file operations on the stage that are not composer operations you are on your own and it is not how the system is intended to work.

create #3336243: Update Package Manager event documentation in package_manager.api.php as a child issue so we can tackle a small part of this

Blocker is in!

Trying to adjust credit given that the patch in #4 makes no actual changes to the documentation.

This looks pretty good to me, but I'm not sure I should give the final sign-off. For the simple reason that I'm too close to this code. I've been living and breathing Package Manager for over a year. Almost any explanation of its internals will make sense to me, because my mind will automatically fill in the gaps.

I think I want this to be reviewed by someone with much less familiarity with the internals before I commit it.

Don't get me wrong: I'm happy to commit it. I did read the diff and the changes made sense.

I merely want a second pair of eyes to review it first, a set of eyes that hasn't had my level of exposure to Package Manager.

Hi all, just chiming in here. I downloaded 3.0.x, applied the patch, and just read package_manager.api.php from top to bottom.

Overall, this absolutely gives me an understanding of how Package Manager works. I had only three things come to mind as I read it:

1. Near line 35: The piece about "only using the same class..." seems like an oddity to me, so might need some explanation why (although that documentation may not need to be in .api.php, but rather in a handbook page or something).
2. Near line 120: I understand event propagation in the JS world, so stopping propagation in that sense makes sense to me. I don't know how to stop propagation, though (is there a Drupal API call EventSubscriber::stopPropagation() or something?), so pointing more specifically to a code example would be good. Also, if you are expecting a consumer/user of Package Manager to have to do the stopping, this is even more important.
3. ...and for the stupid part... lines 160, 170, and 231 go past 80 characters. :)

This is great feedback.

Near line 35: The piece about "only using the same class..." seems like an oddity to me, so might need some explanation why (although that documentation may not need to be in .api.php, but rather in a handbook page or something).

I believe you're referring to:

Only the owner can perform
 * operations on the stage directory, and only using the same class (i.e.,
 * \Drupal\package_manager\Stage or a subclass) they used to create it.

I can see why this would seem odd, and maybe we can clarify it. What it comes down to is that, for Package Manager, "ownership" consists of two things -- a random token, and the fully qualified name of the Stage that you called create() on. You need both of these things in order to reclaim the stage in subsequent requests and do things to it.

Near line 120: I understand event propagation in the JS world, so stopping propagation in that sense makes sense to me. I don't know how to stop propagation, though (is there a Drupal API call EventSubscriber::stopPropagation() or something?), so pointing more specifically to a code example would be good. Also, if you are expecting a consumer/user of Package Manager to have to do the stopping, this is even more important.

Yeah, we would expect code that integrates with Package Manager (a custom validator or event subscriber) to stop propagation if they encounter some catastrophic condition that's going to break any further subscribers. Symfony Event objects have a stopPropagation() method we would expect them to call, so let's add a reference to that.

And while we're at it, let's fix the longer-than-80-characters lines. :)

Went over this from top to bottom and I reorganized and pushed and pulled until I think it's both accurate and comprehensive.

I'd like review from Wim, since he's great at clarity and accuracy...and I'd also like a review from a consumer of Package Manager (that means @bnjmnm or @chrisfromredfin) before we commit.

🏓

Whew!