Contrib.social

Clarify/replace 'stage' terminology in Package Manager

Open on Drupal.org →
Created on 17 September 2024, 7 months ago

Problem/Motivation

Follow-up to ✨ Add Alpha level Experimental Package Manager module Needs review .

Package manager currently uses the word 'stage' to mean several things.

1. A 'staging environment' as in composer stager. @phenaproxima mentioned changing this to sandbox in https://git.drupalcode.org/project/drupal/-/merge_requests/3608#note_376550

2. As a verb, i.e. to 'stage' the stage/sandbox environment.

3. As a synonym of 'phase' or 'step', or the object which manages the lifecycle of a staging directory.

For example:
StageEvent

"The stage event during which this exception is thrown."

"Stage operations"

I personally found this quite confusing when reviewing the code, it's hard to scan something and see what it's referring to at any one time.

Steps to reproduce

Proposed resolution

Not sure. I think when referring to a staging/sandbox directory, it would be good to consistently add 'directory' every time.

But if we can use actual different words for different things (sandbox, phase, step?) that would be better.

Remaining tasks

Opening this as a beta blocker because it is very likely to involve some class renames, even if the only consumers of the API are automatic updates and project browser - but that could get complicated with the contrib versions.

User interface changes

Introduced terminology

API changes

Data model changes

Release notes snippet

📌 Task
Status

Active

Version

11.0 🔥

Component
Base  →

Last updated 6 minutes ago

Created by

🇬🇧United Kingdom catch

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Comments & Activities

  • Issue created by @catch
  • Comment 6 months ago →
    🇬🇧United Kingdom catch
  • Comment 4 months ago →
    🇦🇺Australia larowlan 🇦🇺🏝.au GMT+10
  • Comment 3 days ago →
    🇺🇸United States benjifisher Boston area

    We discussed this issue at 📌 Drupal Usability Meeting 2025-04-11 Active . That issue will have a link to a recording of the meeting.

    For the record, the attendees at the usability meeting were benjifisher, rkoller, and simohell.

    We are not familiar with the code base and the various ways that "stage" is used, but we tried to suggest some guidelines for naming things.

    First, we agree with the first suggestion in the Proposed Resolution. If adding "directory" is too long, then use "staging" or "staged", not "stage" in the context of the staging directory. For example: use StagingBase or StagingDirectoryBase instead of StageBase.

    Second, use "phase" or "step" instead of "stage" when you can. Use "step" if it is possible to move back, or "phase" if only one direction is possible.

    I hope those suggestions are helpful!

contrib.social Blog FAQ Discussions
Production build 0.71.5 2024