Problem

P4_CHANGELIST is set to the latest p4 changelist number across the Perforce server when the list of changelists is empty. This behavior is commented and can be inferred from the code at this link.]

    /**
     * Get the change number for the last change within the scope of the
     * workspace view. If there are no recent changes use the latest change.
     *
     * @return Perforce change
     * @throws Exception push up stack
     */
    public long getClientHead() throws Exception {
        // get last change in server, may return shelved CLs
        String latestChange = getConnection().getCounter("change");
        long latest = Long.parseLong(latestChange);
        P4Ref to = new P4ChangeRef(latest);
        long head = getClientHead(null, to);
        return (head == 0L) ? latest : head;
    } 

However, this edge case is not explicitly documented for P4_CHANGELIST at its description at this link.]

The last Perforce changelist number included in the populated workspace.

The documentation is currently silent about when the workspace is not populated.

Impact

It is likely that the users assume that P4_CHANGELIST always contains a submitted change list number if no error is raised and it is not null. It is likely to be used as a unique identifier of the code version in many places in CI/CD systems.

The latest change list, that may even end up being deleted without any submission, can propagate through the Jenkins systems and hurt the integrity or consistency of builds and their artifacts and logs. 

An explicit documentation may also help the users with understanding the content of P4_CHANGELIST when a workspace is not populated.

Example

If a workspace points to a non-existing depot and the user code uses Jenkins's checkout task with Perforce SCM, P4_CHANGELIST will contain the latest change list number in the Perforce server.

Recommended Solution

Change the documentation as follows:

The last Perforce changelist number included in the populated workspace.

The last Perforce changelist number included in the populated workspace, or the latest changelist number across the Perforce server if no changelist is found in the workspace.