SDP_DeveloperGuide.adoc #1

= SDP Developer Guide
:revnumber: v2025.1
:revdate: 2025-06-10
: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

* _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 _hot fix_ is change made in a release stream that does not involve generating a new SDP tarball. This can be done to push documentation changes to make documentation changes available faster between releases on the live web site, though does not update documentation available. A hot fix can also be done to make individual files available for 'curl' on the site without affecting the version available in the tarball. This usage should be rare and only used in exceptional circumstances where it is acceptable for files on the site to differ from those in the tarball. If contemplating a hot fix involving scripts, a Patch is generally the preferred approach.
* _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 r25.1.32499

  $ 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/r25.1`, that script is part of the SDP 2025.1 release.  Released versions of SDP align with the P4 Server format of `rXX.Y`, where `XX` is a year identifier and `Y` increments with each release in a year.  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/r25.1/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/r25.1` +
`//p4-sdp/r25.2` | `release` | Release process activities are done in release streams, such as updating the Version file and generating final versions of docs and Release Notes. Releases are shipped from this stream, including the initial GA release and any subsequent patch releases for the same major version. Hot Fixes are done in the release stream making them immediately publicly visible.
|`//p4-sdp/main` | `mainline` | Regression test suites target this stream.  Generally, humans should do very little work in this stream, other than Merge Down of hot fixes made in release streams.
| `//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.