Issue #3248976: Add API documentation for Package Manager

package_manager/package_manager.api.php

@@ -129,9 +129,11 @@
  * of the stage life cycle, to ensure that both the active directory and staging
  * area are kept in a safe, consistent state:
  *
- * - No Composer operation which changes the lock file may be executed in the
- *   active directory while a staging area exists, either via Package Manager's
- *   API or externally.
+ * - If the composer.lock file is changed (e.g., by installing or updating a
+ *   package) in the active directory after a staging area has been created,
+ *   Package Manager will refuse to make any further changes to the staging
+ *   area or apply the staged changes to the active directory.
+ * - The Drupal site must not have any pending database updates.
  * - Composer must use HTTPS to download packages and metadata (i.e., Composer's
  *   secure-http configuration option must be enabled). This is the default
  *   behavior.