Issue #3248975 by omkar.podey, tedbow, Theresa.Grannum, Wim Leers: Use "stage...

Issue #3248975 by omkar.podey, tedbow, Theresa.Grannum, Wim Leers: Use "stage directory" instead of  "staging area" or "staging directory" everywhere

automatic_updates_extensions/src/Form/UpdateReady.php

@@ -230,7 +230,7 @@ final class UpdateReady extends UpdateFormBase {
    *   A render array displaying packages that will be updated.
    */
   private function showUpdates(): array {
-    // Get packages that were updated in the staging area.
+    // Get packages that were updated in the stage directory.
     $active = $this->updater->getActiveComposer();
     $staged = $this->updater->getStageComposer();
     $updated_packages = $staged->getPackagesWithDifferentVersionsIn($active);

automatic_updates_extensions/tests/modules/automatic_updates_extensions_test_api/src/ApiController.php

@@ -9,7 +9,7 @@ use Symfony\Component\HttpFoundation\Request;
 use Drupal\package_manager_test_api\ApiController as PackageManagerApiController;
 
 /**
- * Provides API endpoints to interact with a staging area in functional tests.
+ * Provides API endpoint to interact with stage directory in functional tests.
  */
 class ApiController extends PackageManagerApiController {
 

automatic_updates_extensions/tests/src/Build/ModuleUpdateTest.php

@@ -9,7 +9,7 @@ use Drupal\Tests\automatic_updates_extensions\Traits\FormTestTrait;
 use Symfony\Component\Filesystem\Filesystem as SymfonyFilesystem;
 
 /**
- * Tests updating modules in a staging area.
+ * Tests updating modules in a stage directory.
  *
  * @group automatic_updates_extensions
  * @internal
@@ -56,7 +56,7 @@ END;
   }
 
   /**
-   * Tests updating a module in a staging area via the API.
+   * Tests updating a module in a stage directory via the API.
    */
   public function testApi(): void {
     $this->createTestProject('RecommendedProject');
@@ -99,7 +99,7 @@ END;
   }
 
   /**
-   * Tests updating a module in a staging area via the UI.
+   * Tests updating a module in a stage directory via the UI.
    */
   public function testUi(): void {
     $this->createTestProject('RecommendedProject');

package_manager/package_manager.api.php

@@ -10,37 +10,38 @@
  * functionality needed for Drupal to make changes to its own running code base
  * via Composer. It doesn't provide any user interface.
  *
- * At the center of Package Manager is the concept of a staging area. A staging
- * area is a complete copy of the active Drupal code base, created in a
- * temporary directory that isn't accessible over the web. The staging area
- * doesn't include site-specific assets that aren't managed by Composer, such as
- * settings.php, uploaded files, or SQLite databases.
- *
- * Package Manager can run Composer commands in the staging area to require or
- * update packages in it, and then copy those changes back into the live,
+ * At the center of Package Manager is the concept of a stage directory. A
+ * stage directory is a complete copy of the active Drupal code base, created
+ * in a temporary directory that isn't accessible over the web. The stage
+ * directory doesn't include site-specific assets that aren't managed by
+ * Composer, such as settings.php, uploaded files, or SQLite databases.
+ *
+ * Package Manager can run Composer commands in the stage directory to require
+ * or update packages in it, and then copy those changes back into the live,
  * running code base (which is referred to as the "active directory"). The
- * staging area can then be safely deleted. These four distinct operations --
- * create, require, apply, and destroy -- comprise the "stage life cycle."
+ * stage directory can then be safely deleted. These four distinct operations
+ * -- create, require, apply, and destroy -- comprise the "stage life cycle."
  *
  * Package Manager's PHP API is based on \Drupal\package_manager\Stage, which
  * controls the stage life cycle. This class may be extended to implement custom
  * behavior, but in most cases, custom code should use the event system to
  * interact with the stage.
  *
- * Only one staging area can exist at any given time, and it is "owned" by the
- * user or session that originally created it. Only the owner can perform
- * operations on the staging area, and only using the same class (i.e.,
+ * Only one stage directory can exist at any given time, and it is "owned" by
+ * the user or session that originally created it. 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.
  *
  * Events are dispatched before and after each operation in the stage life
  * cycle. There are two types of events: pre-operation and post-operation.
- * Pre-operation event subscribers can analyze the state of the staging area, or
- * the system at large, and flag errors if they detect any problems. If errors
- * are flagged, the operation is prevented. Therefore, pre-operation events are
- * helpful to ensure that the staging area is in a valid state. Post-operation
- * events are simple triggers allowing custom code to react when an operation
- * is complete. They cannot flag errors to block stage operations (although
- * they can use the core messenger and logging systems as needed).
+ * Pre-operation event subscribers can analyze the state of the stage
+ * directory, or the system at large, and flag errors if they detect any
+ * problems. If errors are flagged, the operation is prevented. Therefore,
+ * pre-operation events are helpful to ensure that the stage directory is in a
+ * valid state. Post-operation events are simple triggers allowing custom code
+ * to react when an operation is complete. They cannot flag errors to block
+ * stage operations (although they can use the core messenger and logging
+ * systems as needed).
  *
  * All stage events extend \Drupal\package_manager\Event\StageEvent, and all
  * pre-operation events extend
@@ -50,31 +51,31 @@
  * The stage dispatches the following events during its life cycle:
  *
  * - \Drupal\package_manager\Event\PreCreateEvent
- *   Dispatched before the staging area is created. At this point, the stage
- *   will have recorded which user or session owns it, so another staging area
- *   cannot be created until the current one is destroyed. If subscribers flag
- *   errors during this event, the stage will release its ownership. This is
- *   the earliest possible time to detect problems that might prevent the
- *   stage from completing its life cycle successfully. This event is dispatched
- *   only once during a stage's life cycle.
+ *   Dispatched before the stage directory is created. At this point, the
+ *   stage will have recorded which user or session owns it, so another stage
+ *   directory cannot be created until the current one is destroyed. If
+ *   subscribers flag errors during this event, the stage will release its
+ *   ownership. This is the earliest possible time to detect problems that might
+ *   prevent the stage from completing its life cycle successfully. This event
+ *   is dispatched only once during a stage's life cycle.
  *
  * - \Drupal\package_manager\Event\PostCreateEvent
- *   Dispatched after the staging area is created, which means that the running
- *   Drupal code base has been copied into a separate, temporary location. This
- *   event is dispatched only once during a stage's life cycle.
+ *   Dispatched after the stage directory is created, which means that the
+ *   running Drupal code base has been copied into a separate, temporary
+ *   location. This event is dispatched only once during a stage's life cycle.
  *
  * - \Drupal\package_manager\Event\PreRequireEvent
  *   Dispatched before one or more Composer packages are required into the
- *   staging area. This event may be dispatched multiple times during a stage's
- *   life cycle.
+ *   stage directory. This event may be dispatched multiple times during a
+ *   stage's life cycle.
  *
  * - \Drupal\package_manager\Event\PostRequireEvent
  *   Dispatched after one or more Composer packages have been added to the
- *   staging area. This event may be dispatched multiple times during a stage's
- *   life cycle.
+ *   stage directory. This event may be dispatched multiple times during a
+ *   stage's life cycle.
  *
  * - \Drupal\package_manager\Event\PreApplyEvent
- *   Dispatched before changes in the staging area (i.e., new or updated
+ *   Dispatched before changes in the stage directory (i.e., new or updated
  *   packages) are copied to the active directory (the running Drupal code
  *   base). This is the final opportunity for event subscribers to flag errors
  *   before the active directory is modified. Once the active directory has
@@ -82,58 +83,58 @@
  *   multiple times during a stage's life cycle.
  *
  * - \Drupal\package_manager\Event\PostApplyEvent
- *   Dispatched after changes in the staging area have been copied to the active
- *   directory. This event may be dispatched multiple times during a stage's
- *   life cycle.
+ *   Dispatched after changes in the stage directory have been copied to the
+ *   active directory. This event may be dispatched multiple times during a
+ *   stage's life cycle.
  *
  * - \Drupal\package_manager\Event\PreDestroyEvent
- *   Dispatched before the temporary staging directory is deleted and the stage
+ *   Dispatched before the temporary stage directory is deleted and the stage
  *   releases its ownership. This event is dispatched only once during a stage's
  *   life cycle.
  *
  * - \Drupal\package_manager\Event\PostDestroy
- *   Dispatched after the temporary staging directory is deleted and the stage
+ *   Dispatched after the temporary stage directory is deleted and the stage
  *   has released its ownership. This event is dispatched only once during a
  *   stage's life cycle.
  *
  * The public API of any stage consists of the following methods:
  *
  * - \Drupal\package_manager\Stage::create()
- *   Creates the staging area, records ownership, and dispatches pre- and
+ *   Creates the stage directory, records ownership, and dispatches pre- and
  *   post-create events. Returns a unique token which calling code must use to
- *   verify stage ownership before performing operations on the staging area
- *   in subsequent requests (when the staging area is created, its ownership
- *   is automatically verified for the duration of the current request). See
- *   \Drupal\package_manager\Stage::claim() for more information.
+ *   verify stage ownership before performing operations on the stage
+ *   directory in subsequent requests (when the stage directory is created,
+ *   its ownership is automatically verified for the duration of the current
+ *   request). See \Drupal\package_manager\Stage::claim() for more information.
  *
  * - \Drupal\package_manager\Stage::require()
- *   Adds and/or updates packages in the staging area and dispatches pre- and
- *   post-require events.
+ *   Adds and/or updates packages in the stage directory and dispatches pre-
+ *   and post-require events.
  *
  * - \Drupal\package_manager\Stage::apply()
- *   Copies changes from the staging area into the active directory, and
+ *   Copies changes from the stage directory into the active directory, and
  *   dispatches pre- and post-apply events.
  *
  * - \Drupal\package_manager\Stage::destroy()
- *   Destroys the staging area, releases ownership, and dispatches pre- and
+ *   Destroys the stage directory, releases ownership, and dispatches pre- and
  *   post-destroy events.
  *
  * - \Drupal\package_manager\Stage::getActiveComposer()
  *   \Drupal\package_manager\Stage::getStageComposer()
  *   These methods initialize an instance of Composer's API in the active
- *   directory and staging area, respectively, and return an object which can
- *   be used by event subscribers to inspect the directory and get relevant
+ *   directory and stage directory, respectively, and return an object which
+ *   can be used by event subscribers to inspect the directory and get relevant
  *   information from Composer's API, such as what packages are installed and
  *   where.
  *
  * Package Manager automatically enforces certain constraints at various points
- * of the stage life cycle, to ensure that both the active directory and staging
- * area are kept in a safe, consistent state:
+ * of the stage life cycle, to ensure that both the active directory and stage
+ * directory are kept in a safe, consistent state:
  *
  * - 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.
+ *   package) in the active directory after a stage directory has been created
+ *   ,Package Manager will refuse to make any further changes to the stage
+ *   directory 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
@@ -142,13 +143,13 @@
  * - A supported version of the Composer executable must be accessible by PHP.
  *   By default, its path will be auto-detected, but can be explicitly set in
  *   the package_manager.settings config.
- * - Certain files are never copied into the staging area because they are
+ * - Certain files are never copied into the stage directory because they are
  *   irrelevant to Composer or Package Manager. Examples include settings.php
  *   and related files, public and private files, SQLite databases, and git
  *   repositories. Custom code can use
  *   \Drupal\package_manager\Event\PreCreateEvent::excludePath() to exclude a
- *   specific path from being copied from the active directory into the staging
- *   area, or \Drupal\package_manager\Event\PreApplyEvent::excludePath() to
- *   exclude a specific path from being copied from the staging area back into
- *   the active directory.
+ *   specific path from being copied from the active directory into the stage
+ *   directory, or \Drupal\package_manager\Event\PreApplyEvent::excludePath() to
+ *   exclude a specific path from being copied from the stage directory back
+ *   into the active directory.
  */

package_manager/package_manager.info.yml

 name: 'Package Manager'
 type: module
-description: 'API module providing functionality for staging package installs and updates with Composer.'
+description: 'API module providing functionality to stage package installs and updates with Composer.'
 core_version_requirement: ^9.3 || ^10
 php: 7.4
 dependencies:

package_manager/src/Event/CollectIgnoredPathsEvent.php

@@ -12,7 +12,7 @@ use PhpTuf\ComposerStager\Infrastructure\Value\PathList\PathList;
  * Defines an event that collects ignored paths.
  *
  * Ignored paths are completely ignored by Composer Stager. They are never
- * copied into the staging area from the active directory, or vice-versa.
+ * copied into the stage directory from the active directory, or vice-versa.
  */
 class CollectIgnoredPathsEvent extends StageEvent implements PathListInterface {
 

package_manager/src/Event/ExcludedPathsTrait.php

@@ -20,8 +20,8 @@ trait ExcludedPathsTrait {
    * Adds a path to exclude from the current operation.
    *
    * If called on an instance of \Drupal\package_manager\Event\PreCreateEvent,
-   * excluded paths will not be copied into the staging area when the stage is
-   * created. If called on an instance of
+   * excluded paths will not be copied into the stage directory when the stage
+   * is created. If called on an instance of
    * \Drupal\package_manager\Event\PreApplyEvent, excluded paths will not be
    * deleted from the active directory when staged changes are applied. So,
    * to ensure that a given path is never staged, but also preserved in the

package_manager/src/Event/PostCreateEvent.php

@@ -5,7 +5,7 @@ declare(strict_types = 1);
 namespace Drupal\package_manager\Event;
 
 /**
- * Event fired after a staging area has been created.
+ * Event fired after a stage directory has been created.
  */
 class PostCreateEvent extends StageEvent {
 }

package_manager/src/Event/PostDestroyEvent.php

@@ -5,10 +5,10 @@ declare(strict_types = 1);
 namespace Drupal\package_manager\Event;
 
 /**
- * Event fired after the staging area is destroyed.
+ * Event fired after the stage directory is destroyed.
  *
  * If the stage is being force destroyed, ::getStage() may return an object of a
- * different class than the one that originally created the staging area.
+ * different class than the one that originally created the stage directory.
  *
  * @see \Drupal\package_manager\Stage::destroy()
  */

package_manager/src/Event/PostRequireEvent.php

@@ -5,7 +5,7 @@ declare(strict_types = 1);
 namespace Drupal\package_manager\Event;
 
 /**
- * Event fired after packages are updated to the staging area.
+ * Event fired after packages are updated to the stage directory.
  */
 class PostRequireEvent extends StageEvent {
 

package_manager/src/Event/PreCreateEvent.php

@@ -7,7 +7,7 @@ namespace Drupal\package_manager\Event;
 use Drupal\package_manager\Stage;
 
 /**
- * Event fired before a staging area is created.
+ * Event fired before a stage directory is created.
  */
 class PreCreateEvent extends PreOperationStageEvent {
 

package_manager/src/Event/PreDestroyEvent.php

@@ -5,10 +5,10 @@ declare(strict_types = 1);
 namespace Drupal\package_manager\Event;
 
 /**
- * Event fired before the staging area is destroyed.
+ * Event fired before the stage directory is destroyed.
  *
  * If the stage is being force destroyed, ::getStage() may return an object of a
- * different class than the one that originally created the staging area.
+ * different class than the one that originally created the stage directory.
  *
  * @see \Drupal\package_manager\Stage::destroy()
  */

package_manager/src/Event/PreRequireEvent.php

@@ -5,7 +5,7 @@ declare(strict_types = 1);
 namespace Drupal\package_manager\Event;
 
 /**
- * Event fired before packages are updated to the staging area.
+ * Event fired before packages are updated to the stage directory.
  */
 class PreRequireEvent extends PreOperationStageEvent {
 

package_manager/src/Event/StageEvent.php

@@ -8,7 +8,7 @@ use Drupal\package_manager\Stage;
 use Symfony\Contracts\EventDispatcher\Event;
 
 /**
- * Base class for all events related to the life cycle of the staging area.
+ * Base class for all events related to the life cycle of the stage.
  */
 abstract class StageEvent extends Event {
 

package_manager/src/EventSubscriber/UpdateDataSubscriber.php

@@ -38,9 +38,9 @@ final class UpdateDataSubscriber implements EventSubscriberInterface {
   /**
    * Clears stale update data.
    *
-   * This will always run after any staging area is applied to the active
-   * directory, since it's likely that core and/or multiple extensions have been
-   * added, removed, or updated.
+   * This will always run after any stage directory changes are applied to the
+   * active directory, since it's likely that core and/or multiple extensions
+   * have been added, removed, or updated.
    */
   public function clearData(): void {
     $this->updateManager->refreshUpdateData();

package_manager/src/Exception/StageException.php

@@ -5,7 +5,7 @@ declare(strict_types = 1);
 namespace Drupal\package_manager\Exception;
 
 /**
- * Base class for all exceptions related to staging operations.
+ * Base class for all exceptions related to stage operations.
  *
  * Should not be thrown by external code.
  */

package_manager/src/PathExcluder/GitExcluder.php

@@ -10,7 +10,7 @@ use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 use Symfony\Component\Finder\Finder;
 
 /**
- * Excludes .git directories from staging operations.
+ * Excludes .git directories from stage operations.
  *
  * @internal
  *   This is an internal part of Package Manager and may be changed or removed
@@ -41,7 +41,7 @@ final class GitExcluder implements EventSubscriberInterface {
   }
 
   /**
-   * Excludes .git directories from staging operations.
+   * Excludes .git directories from stage operations.
    *
    * @param \Drupal\package_manager\Event\CollectIgnoredPathsEvent $event
    *   The event object.

package_manager/src/PathExcluder/NodeModulesExcluder.php

@@ -10,7 +10,7 @@ use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 use Symfony\Component\Finder\Finder;
 
 /**
- * Excludes node_modules files from staging areas.
+ * Excludes node_modules files from stage directories.
  *
  * @internal
  *   This is an internal part of Package Manager and may be changed or removed
@@ -32,7 +32,7 @@ class NodeModulesExcluder implements EventSubscriberInterface {
   }
 
   /**
-   * Excludes node_modules directories from staging operations.
+   * Excludes node_modules directories from stage operations.
    *
    * @param \Drupal\package_manager\Event\CollectIgnoredPathsEvent $event
    *   The event object.

package_manager/src/PathExcluder/PathExclusionsTrait.php

@@ -8,7 +8,7 @@ use Drupal\package_manager\Event\CollectIgnoredPathsEvent;
 use Drupal\package_manager\Event\StageEvent;
 
 /**
- * Contains methods for excluding paths from staging operations.
+ * Contains methods for excluding paths from stage operations.
  */
 trait PathExclusionsTrait {
 

package_manager/src/PathExcluder/SiteConfigurationExcluder.php

@@ -9,7 +9,7 @@ use Drupal\package_manager\PathLocator;
 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
 /**
- * Excludes site configuration files from staging areas.
+ * Excludes site configuration files from stage directories.
  *
  * @internal
  *   This is an internal part of Package Manager and may be changed or removed
@@ -41,7 +41,7 @@ class SiteConfigurationExcluder implements EventSubscriberInterface {
   }
 
   /**
-   * Excludes site configuration files from staging operations.
+   * Excludes site configuration files from stage operations.
    *
    * @param \Drupal\package_manager\Event\CollectIgnoredPathsEvent $event
    *   The event object.