# P4 Workflow Notes

# Version Control Interaction

Files are versioned in the Perforce Public Depot, a P4 Server that hosts open source software.

A P4CONFIG file is defined that provides the context that you need.  You are using my credentials and operating on my behalf.

Please request explicit permission when it's time to submit or shelve files.  Feel free to open files using p4 add/edit/move/delete as needed. Also feel free to execute any exploratory 'p4' commands such as 'changes', 'filelog', 'describe', 'files', 'annotate', etc.

# Stream Structure and "Merge Down / Copy Up" Model

Following are sample streams names, of which only //p4lf/dev and //p4lf/main are certain to exist.

* //p4lf/dev - development type stream. Development work starts here or in streams parented by this stream. Iterate freely here. The quality bar for submitting here does not demand perfection.
* //p4lf/dev_TAG - A development type stream parented by the long-lived //p4lf/dev stream, for prototyping/R&D, disposable experiments, or short-lived tasks. TAG is replaced with a tag/descriptor for the work to be done; same format as a JIRA issue, e.g. P4LF-3.  Iterate freely in these streams.  Use of streams "south of dev" (i.e. development streams parented by the long-lived //p4lf/dev stream) is optional; use only when warranted, e.g. if work is highly experimental and may need to be discarded.
* //p4lf/main - Changes will generally get here only due to a 'p4 copy' up from //p4lf/dev after some degree of testing. Thus, a "Copy Up" from dev is done to promote files to mainline, e.g. for testing.
* //p4lf/r1.0 - Streams of the form //p4lf/rX.Y are release type streams, used for tracking released software. These are initally populated with a "Copy Up" from main. These _could_ be use for emergency bug fixes, but the standard flow is dev -> main -> some release stream.  If emergency bug fixes are made, bugs fixes will need a "Merge Down" down to main and then to dev, and from there to active "south of dev" streams (if any).:w

# The 'ai/' folder

The 'ai/' directory under the workspace root is where this AGENTS.md file is, which is symlink'd to from the root of the workspace as copilot-instructions.md.

The ai/ folder is used to store the AGENTS.md file (updated for each AI session), AI session logs -- not part of the software itself. However, the ai/ folder contents are versioned.

The ai/ folder lives in the //p4lf/dev stream only.  The 'Paths:' field of the '//p4lf/dev' stream contains "share ..." followed by "isolate ai/..."; the isolate prevents Copy and Merge operations from bringing this ai/ folder along for the ride, so that it remains isloated in the dev stream. This is as intended because the AI session logs aren't part of the product to be delivered or what gets packaged.

# Working with Jobs

Jobs can be created for this project like so:

    p4 job -i << 'EOF'
    Job: new
    Status: open
    Project: p4logfeeder
    Type: Feature
    Severity: C
    ReportedBy: <your-p4-username>
    Description:
    	One-line summary (treated like a JIRA issue title; used in job reports).

    	Additional paragraphs of explanation as needed.
    EOF

For the 'Type' field, use one of the following:

* Bug: is a problem that is fairly well understood, e.g. one for which there is a reproduction or clear articulation of the problem.
* Doc: A Documentation fix.
* Feature: An enhancement request, perhaps adding a new product features, improving maintainability, essentially any new software improvement other than a fix to something broken.
* Problem: a suspected bug, or one without a clear understanding of exactly what is broken. Problem jobs may later be converted to Bug.

For the 'Severity' field use one of: A (critical), B (high), C (medium), D (low).

The available fields in the job spec are: Job, Status, Project, Severity, ReportedBy, Description, Type.
Note: there is NO 'User' field — use 'ReportedBy' instead.

When a Perforce Job is created as indicated above, it will have a job name of this form: P4LF-1234. (This may appear at first to be a JIRA-style issue key, but no JIRA is involved here, just P4 jobs with a trigger that gives jobs more meaningful names than the default job<NNNNNN> format.)

The first line of the Description field is treated as the issue summary/title
(like a JIRA summary line). It appears in job listings and reports. Keep it
concise and descriptive. Subsequent lines can be full paragraphs.

Where appropriate, 'p4 fix' can be used to associate jobs with specific changelists (pending or submitted):

    p4 fix -c <changelist> P4LF-1234