Human-friendly workspace branch naming

[manuelkiessling]

Summary

Make workspace branch names more human-friendly by using a structured, readable format that includes timestamp, user identity, and short workspace ID.

Desired format

<YYYY-MM-DD H:i:s>-usermailATdomainDOTtld-SHORTWORKSPACEID

Components:

• Date/time: YYYY-MM-DD H:i:s (e.g. 2025-02-05 14:30:22) — when the branch was created
• User: usermailATdomainDOTtld — commit author email with @ → AT and . → DOT so the branch name is filesystem/URL-safe and readable (e.g. manuelATkiesslingDOTnet)
• Short workspace ID: first 8 characters of the workspace UUID (same as today) for uniqueness and traceability

Example: 2025-02-05 14:30:22-manuelATkiesslingDOTnet-a1b2c3d4

Current behavior

• Branch names are generated in WorkspaceSetupService::generateBranchName() (see src/WorkspaceMgmt/Domain/Service/WorkspaceSetupService.php).
• Current format: ws-<shortId>-<timestamp> with timestamp Ymd-His (e.g. ws-a1b2c3d4-20250205-143022).
• User email is not available in the setup flow today; it is only used later for commits and PR body (e.g. in WorkspaceGitService, WorkspaceMgmtFacade::commitAndPush / ensurePullRequest).

Implementation notes

1. Pass user email into setup

   • dispatchSetupIfNeeded is called from ChatBasedContentEditorController::startConversation(), where the current user (and thus AccountInfoDto / email) is available.
   • Extend the chain so that when a user triggers setup, their email is passed through:
     • Optional: WorkspaceMgmtFacadeInterface::dispatchSetupIfNeeded(string $projectId, ?string $userEmail = null) and pass $accountInfo->email from the controller.
     • SetupWorkspaceMessage would need to carry an optional ?string $userEmail = null.
     • WorkspaceSetupService::setup() / performSetup() would need to receive (or resolve) user email and pass it to generateBranchName().

2. Branch name generator

   • Change generateBranchName(string $workspaceId) to something like generateBranchName(string $workspaceId, ?string $userEmail = null).
   • Build the three segments:
     • Timestamp: DateAndTimeService::getDateTimeImmutable()->format('Y-m-d H:i:s') (note: spaces and colons are valid in Git branch names; if any tooling disallows them, consider Y-m-d_H-i-s or similar).
     • Sanitized email: replace @ → AT, . → DOT (and optionally normalize to lowercase for consistency).
     • Short workspace ID: mb_substr($workspaceId, 0, 8) (existing behavior).
   • When $userEmail is null (e.g. setup triggered from a path that has no user, or legacy callers), fall back to the current format or a placeholder (e.g. unknownATuserDOTlocal or keep ws-<shortId>-<timestamp> for backward compatibility).

3. Git branch name constraints

   • Git allows spaces and colons in branch names; some CI/URL tools may not. If we need to avoid them, use e.g. Y-m-d_H-i-s instead of Y-m-d H:i:s.

4. Database / storage

   • Workspace.branchName is already stored (length 255). The new format is similar in length; verify max length for the chosen timestamp and email sanitization (e.g. long emails with many DOT segments).

5. Tests

   • Unit tests for the new branch name formatter (timestamp format, email sanitization, short ID, null email fallback).
   • Adjust any existing tests that assert on the current ws-... format.

6. Docs

   • Update docs/plans/project-workspace-conversation-workflow-high-level.md (and any other docs that describe branch naming) to the new format.

Acceptance criteria

• New branches use the format <YYYY-MM-DD H:i:s>-usermailATdomainDOTtld-SHORTWORKSPACEID when user email is available.
• When user email is not available, behavior is defined (fallback format) and documented.
• Existing workspaces (already have a branch name) are unchanged; only new setups use the new format.
• Branch names remain valid for Git and for GitHub (URLs, PRs, CI).
• Unit tests cover the new formatter and fallback.

References

• Current branch name generation: sitebuilder-webapp/src/WorkspaceMgmt/Domain/Service/WorkspaceSetupService.php (generateBranchName)
• Setup trigger: WorkspaceMgmtFacade::dispatchSetupIfNeeded ← ChatBasedContentEditorController::startConversation (has $accountInfo->email)
• Message: SetupWorkspaceMessage (currently only workspaceId)

[manuelkiessling]

Clarification: User email is required, not optional. We always have one when setup runs:

• Editor flow: startConversation() has #[CurrentUser] and $accountInfo->email.
• Prefab flow: AccountCoreCreatedSymfonyEventSubscriber has $event->accountCoreId; resolve to account email via AccountFacade::getAccountInfoById().

The user whose email appears in the branch name is whoever triggers the branch creation (first user in the editor session, or the new account in the prefab flow). That’s intentional and acceptable.

The issue body in the repo (e.g. .github-issue-branch-naming.md) has been updated to require userEmail and to document both call sites.