# P4 Information

## General Info

We're working in P4 here.  You're currently in a P4 workspace on the //test-install_sdp/dev stream on a P4 Server known as the Perforce Public Depot, with P4PORT=public.perforce.com:1666 (or sometimes P4PORT=54.241.106.223:1666, using an IP address to workaround local Perforce VPN/DNS issues.)

The local workspace root directory is one level up from the directory where the CLAUDE.md and P4Info.md files exists.  You are approved to have access to the entire P4 workspace.

## P4CONFIG Files

Ask each session and I'll instruct which P4CONFIG to use for that session:

* Set P4CONFIG to .p4config to use my credentials, and thus operate on my behalf.
* Set P4CONFIG to .p4config.bot_Claude_Anthropic to use your own credentials (P4USER=bot_Claude_Anthropic), when you are asked to operate independently.

In either scenario, you won't need to login. A ticket will be generated for you. That said, it's a good idea to make sure you have a valid ticket with plenty of time left on it by doing `p4 login -s` at the beginning of any session.

**Self-service login (added 2026-08-21):** the bot_Claude_Anthropic identity's password for the Public Depot is stored at `~/pub/.p4passwd.bot_Claude_Anthropic` (and, separately, the PPN server's password at `~/ppn/.p4passwd.bot_Claude_Anthropic` -- see `//BattleSchool/Gen7/ai/AGENTS.md` for that one). If `p4 login -s` shows an expired/missing ticket, log in directly rather than asking the user to renew it:

    export P4CONFIG=.p4config.bot_Claude_Anthropic
    p4 login < ~/pub/.p4passwd.bot_Claude_Anthropic

**Log in 3 times in a row at the start of a session to get the maximum ticket duration.** Per the user: a login when you have *no* existing ticket only gets the ticket to some baseline duration; each subsequent login while a ticket already exists extends it by 1/3 of the max duration, so repeating the login a few times converges on the full duration (confirmed 2026-08-21: three logins in a row took the Public Depot ticket to the full 24 hours). Never `cat`/echo the password file's contents -- always pipe it directly into `p4 login`'s stdin.

**On this local Mac workspace, always set `P4CONFIG` to a bare filename (e.g. `.p4config.bot_Claude_Anthropic`), never an absolute path.** This environment's P4CONFIG files are designed to be layered (see "How the P4CONFIG Hierarchy Works" below) -- a bare filename makes P4 walk up from the current directory collecting settings from every level (P4PORT/P4USER from a high-level file, P4CLIENT from a low-level one). An absolute path reads *only* that one file, silently dropping whatever's set higher up (typically P4PORT). **Lesson learned (2026-08-20):** did exactly this by habit (carried an absolute path over from an unrelated tool call) and ended up resolving `P4PORT` from some other fallback entirely -- `p4 info` still returned a real, valid-looking server, just the wrong one, and every ticket/login check failed confusingly against it until the mistake was spotted.

**This bare-filename rule is specific to this local Mac layout, though.** Other environments (e.g. the deployed BSW lab environment) use *self-contained* P4CONFIG files instead -- each one sets everything needed (P4PORT/P4USER/P4CLIENT) in a single file, with no layering to preserve -- so those are correctly referenced by absolute path. See `//BattleSchool/Gen7/ai/AGENTS.md`'s "P4CONFIG Convention: Local Mac vs. the Deployed Lab Environment" section for that case. The rule is really "match the convention the files were designed for," not "absolute paths are always wrong."

### How the P4CONFIG Hierarchy Works

We use nested P4CONFIG files across a couple of local directory trees, one per P4 Server:

* `~/pub` sets P4USER and P4PORT for the Perforce Public Depot server.
* `~/ppn` sets P4USER and P4PORT for the Perforce Partner Network (PPN) server.

Subdirectories within each of those trees (e.g. this `test-install_sdp` workspace under `~/pub`) add their own P4CONFIG file that sets P4CLIENT, which varies from one subdirectory to another. Both `.p4config` (my credentials) and `.p4config.bot_Claude_Anthropic` (your credentials) are available at every level in both the `~/pub` and `~/ppn` trees, so the P4CONFIG env var selects the identity and the directory-level files together determine P4USER/P4PORT/P4CLIENT.

### Known Workspace Directories

* `~/pub/test-install_sdp` -- `//test-install_sdp/dev` (this project's own test-suite source; also see `ai_dev_support/` here, isolated per the rule above).
* `~/pub/tt` -- `//guest/tom_tyler/sw/main/install_sdp/dev/bin` (the old, now-frozen/deprecated home of the SDP Installer Test Suite; see the "We've Moved" task).
* `~/pub/p4-sdp_dev_rebrand` -- `//p4-sdp/dev_rebrand` (the SDP itself; your workspace, but I use it under my own `bot_Claude_Anthropic` identity and submit as myself there too).
* `~/ppn/BattleSchool/aws/pem/us-east-2` -- `//BattleSchool/main/aws/pem/us-east-2` (ssh wrapper scripts and pem files for the AWS test fleet).

### Editing On-Host (Fleet Machines) Instead of a Local Mac Workspace

For SDP or test-suite changes, it doesn't have to be a local Mac workspace (the directories above) -- if a fleet machine was bootstrapped via `bootstrap_test_machine.sh -mode advanced` (i.e. `swap_source.sh`'s DVCS clones there are read/write, not the read-only `ftp` user), I can edit and test directly on that machine, under my own `bot_Claude_Anthropic` identity: `/opt/perforce/dev/sdp` for SDP changes, `/opt/perforce/dev/bin` for SDP Installer Test Suite changes. This is often the better choice when the point is to test-and-iterate in place before committing, rather than editing locally and redeploying to verify.

After `p4 submit` on the machine, remember to `p4 push` too -- DVCS clones need an explicit push to get local submits back to the Public Depot; a local Mac workspace submit doesn't need this since it's a regular (non-DVCS) client directly against the server. Either approach (local Mac workspace, or on-host DVCS clone) is fine; pick whichever fits what's being done.

**Lesson learned (2026-08-12):** editing on the Mac workspace means submitting *before* the change can actually be tested (a fresh-machine SDP behavior fix needs a real machine to verify against), whereas editing on-host means iterating -- edit, test, edit again -- *before* committing to a submit+push at all. Got this wrong once: fixed a P4D 2026.1 Secure-By-Default issue on the Mac workspace, submitted, deployed to the canary, found the fix didn't actually work, had to submit a new change to correct it -- two changelists for one fix, when iterating on-host first would have caught it before any submit. When a fix needs a real machine to verify (not just ShellCheck/local logic), prefer editing on-host.

### P4 Config Precedence

P4 clients (like `p4`) can get context variables (`P4PORT`, `P4USER`, `P4CLIENT`, `P4IGNORE`, `P4CHARSET`, etc.) from several sources. From highest to lowest precedence:

1. Command-line "general" options (before the specific command), e.g. `-u <P4USER>`.
2. P4ENVIRO settings.
3. P4CONFIG file(s). If `P4CONFIG` is set to a bare filename (as it is here, e.g. `.p4config.bot_Claude_Anthropic`) rather than an absolute path, P4 looks for that filename in the current directory and every parent directory, and uses the *collective* set of values found -- when the same variable is set in more than one, the one in the directory nearest the current working directory wins. If `P4CONFIG` is set to an absolute path, only that one file's values are used.
4. Shell environment variables.
5. Hard-coded client defaults (e.g. `P4PORT=perforce:1666`, `P4USER=<your OS user>`).

So P4CONFIG files win over shell environment variables, not the other way around -- worth remembering when a script exports `P4PORT`/`P4USER` for convenience: those exports only take effect where no closer P4CONFIG file (or P4ENVIRO/command-line option) already supplies that variable.

## P4 Code Review (fka Helix Swarm) URLs

The Public Depot's P4 Code Review instance is at `https://workshop.perforce.com`. URLs follow the pattern `https://workshop.perforce.com/<mode>/<depot-path>`, where `<mode>` is one of:

* `files` -- shows version control info (revision history, etc.) alongside the content; the general-purpose browsing view.
* `view` -- a nicely rendered view, useful for content meant to be looked at as a document, e.g. HTML.
* `download` -- raw file content with no HTML wrapper, suitable for `curl`/`wget`. Confirmed working for stream depot paths too, not just Classic ones, e.g. `curl -O https://workshop.perforce.com/download/test-install_sdp/dev/InstallSDP-TestServerSetup.md`. This is how a bootstrap script can pull itself onto a fresh machine before any P4 client tooling is available there.

## P4 Session Start Situational Awareness

For P4 situational awareness, it's generally a good idea to start a session with some basic commands like:
* `p4 login -s` - already covered
* `p4 opened` (and if files are opened to numbered changeslist, `p4 describe -s` and maybe `p4 diff` on any opened files.
* `p4 status` to see what's sitting around outside version control.

We don't need to check every time, but be aware there are some P4IGNORE files (named `.p4ignore`) that affect how `p4 status` works.

## Avoid Unnecessary Merges: Sync Before Edit

Before doing `p4 edit` (or `p4 add`) on a file you haven't touched yet this session, `p4 sync` it (or the surrounding directory) first. If someone else submitted a newer revision since your workspace last synced, opening for edit against a stale revision means you'll be told to `p4 resolve` before you can submit.

That resolve is often trivial (as it was the one time this came up, syncing cleanly with 0 conflicting chunks), but it isn't guaranteed to be -- and it's easy to avoid entirely by syncing first. This matters most in shared/personal depot areas we don't work in constantly (e.g. someone else's workspace, or a path we haven't touched in a while), where we're less likely to already be at head.

## P4 Changelist Descriptions

Please add a line to any P4 changelist descriptions generated to indicate the agent and model used. Do this regardless of whether operating using my credentials or your own.

## The ai_dev_support Folder is Isolated

The `//test-install_sdp/main` stream's Paths field includes `isolate ai_dev_support/...`, and the `dev` stream (and other child streams) inherit that.  The intent: AI session logs and other support files in `ai_dev_support/` have value (training, understanding history, audit, etc.) but aren't part of the product itself, so they're a good fit for the 'isolate' stream feature.  When we later promote from `dev` to `main` (a "Copy Up"), the `ai_dev_support/` folder is exempted from the Merge Down / Copy Up flow.

General rule: submits touching the `ai_dev_support/` folder should be mutually exclusive with submits touching any other folder -- don't mix `ai_dev_support/` changes into the same changelist as product changes, and vice versa.