SDP_DeveloperGuide.adoc #2

= SDP Developer Guide
:revnumber: v2026.1
:revdate: 2026-09-03
:doctype: book
:icons: font
:toc:
:toclevels: 5
:sectnumlevels: 4
:xrefstyle: full
// Attribute for ifdef usage
:unix_doc: true

== DRAFT NOTICE

WARNING: This document is in DRAFT status and should not be relied on yet.  It is a preview of a document to be completed in a future release.

== Preface

This guide is to aid people who contribute to the P4 Server Deployment Package (P4SDP).  This includes Perforce Staff and contributors from the general public.

== Terminology

* _Emergency Bug Fix_: A direct edit made in an already-cut release stream that changes something which actually ships in that stream's tarball -- a script, not just a doc page -- bypassing the normal `dev` -> `main` -> release-stream flow on purpose, to get a critical fix out faster than a full new Patch Release would allow. Always requires bumping that release stream's `Version` file and republishing its tarball. This is exceptional by design; if it starts feeling routine, that's a signal to cut a real Patch Release instead. See the link:ReleaseProcessOverview.md[Release Process Overview]'s "Hot Fixes and Emergency Bug Fixes" section.
* _GA Release_: A General Availability (GA) release is the first release of a new major version.  It includes a new SDP tarball as well as updates to files available on the web site with standard/published links.
* _Hot Fix_: A direct edit made in a release stream (or in `main`, ahead of the next Copy Up) that touches only web-facing, non-shipped content -- e.g. doc pages or `README.md` -- without generating a new SDP tarball. This is the preferred, lower-risk way to make an out-of-band correction, and should be the common case; it's not forbidden to go further, but if the fix needs to touch a script that actually ships, see _Emergency Bug Fix_ instead.
* _Merge Down, Copy Up_: A mantra for a well-designed release process.  See the link:https://workshop.perforce.com/projects/perforce_software-pds[Perforce Directory Standard (PDS)] for information about this.
* _Patch Release_: A Patch Release is functionally identical to a GA release, in that it includes a new SDP tarball and updates to files on the web site.  Any SDP release between major version releases of the P4 Server is a Patch.
* _Ready 5_: The property of a release process that ensures the team can always shift priorities and ship a patch quickly, even as various development tasks are in different states of readiness.  Doing work properly and keeping the `mainline` clear of work that is not ready to ship is key to maintaining readiness.

== Script Versioning

Many individual SDP scripts are versioned using the `+k` "keyword expansion" file type modifier. This file type modifier causes the P4 Server to update keywords in the content of the versioned file, e.g. our scripts, with a new version identifier each time the script is submitted.

Scripts that use this versioning method support the `-V` (version check) option, which gives results like these examples:

  $ ccheck.sh -V
  ccheck.sh version r26.1.0.33441

  $ ccheck.sh -V
  ccheck.sh version DEV_C2S.31580

Due to the way we are using Streams, the path to the versioned file contains meaningful information about which version of SDP the script is released with.  For example, if the script path starts with `//p4-sdp/r26.1.0`, that script is part of the SDP 2026.1 GA release. Released versions of SDP align with the P4 Server format of `rXX.Y`, with an additional `.Z` patch digit that's always present (never omitted), where `XX` is a year identifier, `Y` increments with each major release in a year, and `Z` is `0` for the GA release and increments with each patch after it (e.g. `r26.1.0` for GA, `r26.1.1` for the first patch). Unreleasd versions, such as those being developed and tested, use an ALL-UPPERCASE form of the development stream name, .e.g. DEV_C2S relates to the `//p4-sdp/dev_c2s` development stream. The uppercase is used to emphasize that version is not released.

The number at the end is the changelist number of the individual change that produced that latest version of the script. For released versions, this changelist will be due to release-process related activities rather the development code changes.

The following standard block of code (bash in this example) illustrates how the keyword is used to automatically update the version number with each submit.

  # Version ID Block. Relies on +k filetype modifier.
  #------------------------------------------------------------------------------
  # shellcheck disable=SC2016
  declare VersionID='$Id: //p4-sdp/r26.1.0/doc/gen/gen_script_man_pages.sh#2 $ $Change: 31472 $'
  declare VersionStream=${VersionID#*//}; VersionStream=${VersionStream#*/}; VersionStream=${VersionStream%%/*};
  declare VersionCL=${VersionID##*: }; VersionCL=${VersionCL%% *}
  declare Version=${VersionStream}.${VersionCL}
  [[ "$VersionStream" == r* ]] || Version="${Version^^}"

The line that defines `VersionID` is modified by the P4 Server upon submit, with the '$Id:$` and `$Change:$` tags being replaced. This ensures that the version is reliably updated each time the script changes.  Note that in this bash example, single quotes are used rather than double quotes to prevent the bash shell from interpreting `$Id` and `$Change` as bash script variables. The `shellcheck disable=SC2016` comment silences as ShellCheck warning about accidental usage of single quotes suppressing expansion of variables. In this case, that is exactly the intent.

== Working in Streams

Different types of work are done in different streams:

// [%autowidth,cols="a,a,a",options="header",] <-- The autowidth looked ugly.
[cols="24%a,15%a,61%a",options="header",]
|===
|Stream Name|Type|Description of Work
|`//p4-sdp/r*` +
{empty}
Examples: +
{empty}
`//p4-sdp/r26.1.0` +
`//p4-sdp/r26.1.1` | `release` | Release process activities are done in release streams, such as updating the Version file and generating final versions of docs and Release Notes. Each release -- the initial GA and every subsequent patch -- gets its own freshly-cut release stream from `main`; release streams are never patched or otherwise modified in place after they ship. See `doc/ReleaseProcessOverview.md` for the full process.
|`//p4-sdp/main` | `mainline` | Reflects whatever was most recently released. Regression test suites target `dev` (the release candidate), not `main` -- `main` only receives content via Copy Up from `dev` as part of cutting a release. Humans should do very little direct work in this stream outside of the release process itself.
| `//p4-sdp/dev` | `development` | This is the default development stream.  Work on features that are committed to be in the next release can be done directly in this stream, such as straightforward bug fixes and small, low-risk features.  Anything submitted to this stream _must_ be in a state where, if released today due to a need to ship an urgent patch possibly unrelated to the current change being submitted, it would be a Good Thing.  Submitting something to the default dev branch is in effect saying, "Pending verification by regression test suites, this change is good enough to be shipped." Don't submit something in the default dev stream unless you intend to do any necessary iteration (e.g. based on regression test suite results) in short order.
| `//p4-sdp/dev_*` +
{empty}
Examples: +
{empty}
`//p4-sdp/dev_c2s` +
`//p4-sdp/dev_rebrand` +
`//p4-sdp/dev_SDP-1265` | `development` +
or +
`sparsedev`| Development tasks are done in feature streams if it is not certain they are ready or whether they will be included in the next release. The `tag` is a short tag name referencing the work, e.g. "c2s" for "Classic to Streams development work", or the tag can even be a JIRA issue tag, e.g SDP-1265. Types of work done in development streams may include:

* Projects with uncertainty in their development time frames, possibly large projects and/or those requiring significant iteration.
* Prototype or Research and Development work that may never be released. Work in dev* streams can terminate stream and never be promoted, or deferred indefinitely.

When choosing `development` vs. sparsedev stream type, consider these factors:

* Use `development` streams if a plan on using push/fetch to work offline; as fetching doesn't a `sparsedev` stream only fetches stream-resdient files, not the whole workspace.
* Use `sparsedev` if you're working on focused changes, e.g. to just a few scripts or files.

|===

== Code Reviews

Code reviews can occur in any stream. Both pre- and post-commit reviews are allowed.  Reviews in the default dev stream can be done for changes initiated directly in the default dev stream, as well as Copy Up changes from dev* streams, thus reviewing the sum of a series of iterative changes in a lower dev* stream in a single review. More granular reviews can also occur in directly in dev* streams.

== P4 Code Review and Stream Paths

[appendix]
== Other Documentation

See Also: 

* link:ReleaseProcessOverview.html[SDP Release Process Overview].

[appendix]
== DRAFT NOTICE

WARNING: This document is in DRAFT status and should not be relied on yet.  It is a preview of a document to be completed in a future release.