This document describes the process used to release the Server Deployment Package (SDP). This is intended for staff developing the SDP.
A dedicated SDP workspace should be used for releasing the SDP, separate from any you might use for SDP development. This dedicated release workspace should not contain any cruft files such as editor temp files. The release process mechanisms prevents known-cruft files from being added such as *~ files and .DS_Store files on Mac. Using a clean dedicated release workspace guarantees no local excess files can sneak into the packaging process.
Develop and test changes in dev branch. This will occur over time.
Determine if the SDP release is to be Major, Patch, or Doc Only.
Starting with the 2021.2 release of P4D, SDP major releases are tied to the P4D release schedule, with SDP releases occuring when P4D releases, plus or minus no more than 2 business days.
Other releases will be Patch releases if there are any functionality changes, or Doc Only releases, where changes since the last release affect only documentation. The SDP documentation is key to its value, worth doing patch updates including only documentation changes.
Verify that the SDP regression test suite is successful.
The SDP regression test suite is only accessible from the Perforce VPN.
If not already done during development, create jobs and associate them with changelists in the dev
branch, e.g. using p4 fix -c <CL> SDP-<NNN>
. We don't need a job for every change. Create jobs to cover the essentials of what changed. Folks who want the gory details can look at changelists, but folks looking only at jobs should get a summary of what's new in this release or patch, and if appropriate, what to be aware of when taking this release. The first line of the job description will be incorporated into the release notes, so make the first line a good headline for the job.
Load the latest SDP tools shell environment.
Change to the dir in your SDP workspace corresponding to //guest/perforce_software/sdp/tools
, and do p4 -s sync
followed by source ./env.sh
in that directory.
Ensure the dev
branch is updated from main.
This ensures any hot fixes that my have been made directly in main
branch are considered for incorporation in the formal release.
$ p4 merge -n -b perforce_software-sdp-dev
All revision(s) already integrated.
If there is anything to merge, take care of it in your regular SDP development workspace, not the release workspace. If needed, file new jobs and associate them with changes. Upon completion of any needed merge work.
Update AsciiDoc revnumber
and revdate
.
This step applies to major releases only; skip this for patch releases.
In all *.adoc files, verify that the :revnumber:
and :revdate:
tags in the file refer to the correct SDP release version and date the file was last modified -- updating it to the current date.
The fields look something like this example in each *.adoc file:
:revnumber: v2021.1
:revdate: 2021-10-20
Review documents for any out-of-date references or content.
Ensure generated documentation is current.
Run the gen_script_man_pages.sh -submit
and observe the output. It may or may not create a new changelist in //guest/perforce_software/sdp/dev/doc/gen/...
, depending on whether the underlying scripts have changed since they were last generated.
Run the rel_notes.sh
script to update the Version and Release Notes files in the dev branch. (NOTE: If you are runnign this on Mac OSX, do a brew install bash
first to get a modern version of bash, v4.x+, and then run bash rel_notes.sh
to override the version of bash executed.) If the jobs listed in the generated release notes aren't complete enough, revert the Version
and doc/ReleaseNotes...
files, update the job descriptions, and try again.
If this is a new major release, manually update the section, "What's New in <this version>". Summarize what to be aware of when taking this release, summarize what's in the release, and document details to be aware of when upgrading to this release. This script is interactive and prompts for the major version, e.g. 2020.1 (proposing as a default whatever the previous value was). It takes no command line arguments. It also prompts for the Release Type, e.g. GA or Patch.
The rel_notes.sh
wants your workspace to be clean, with the latest files sync'd, nothing checked out in the dev
and main
branches, and that a p4 status
command reporting nothing to reconcile.
WARNING: If you need to do a partial release (i.e. if you need to hold some changes back in the dev
branch), be sure to remove jobs referencing files you do not intend to promote. Note that partial releases are discouraged.
WARNING: If a partial release was done previously and files are now ready to be released, you'll need to add those jobs to the release notes manually. Doing a partial release will confuse the mechanism used in rel_notes.sh
to determine what jobs were fixed since the last release, as it does a p4 fixes
command in the dev branch looking for fixes since the last release changelist number in the Version file. Even a partial release updates the changelist number, and thus will require manual intervention to get the list of jobs correct.
The rel_notes.sh
script leaves the Version and Release Notes files checked out in a pending changelist for you to review. It also provides a list of commands to execute to complete the submit of the release notes. Submit that change manually when ready, e.g. after adding the "What's New in <this version>" content. Also, follow the guidance at the end of the output in the script about running the make clean all
and p4 rec
commands as directed in the output of the rel_notes.sh
script. That tail end of that output should look something like this:
Executing: p4 edit -c 27821 //guest/perforce_software/sdp/dev/doc/ReleaseNotes.html //guest/perforce_software/sdp/dev/doc/ReleaseNotes.pdf
//guest/perforce_software/sdp/dev/doc/ReleaseNotes.html#24 - opened for edit
//guest/perforce_software/sdp/dev/doc/ReleaseNotes.pdf#25 - opened for edit
Massage the release notes and changelist description as needed.
Then do:
cd /re/sdp/dev/doc
make clean all
p4 rec -c 27821
p4 -s submit -c 27821
Follow those commands as instructed. These steps will ensure generated documentation is current with the latest *.adoc files.
Push the files to main.
Change to the dev
branch directory in your workspace. Run mdcu.sh
(Merge Down/Copy Up) script, which takes no arguments and is not interactive. That script creates a pending changelist with the Copy Up main.
Massage the generated pending changelist description if desired.
WARNING FOR PARTIAL RELEASES: If this is to be a partial release, revert any files that are not ready to be released from the main branch. Also be sure the reverted files correlate to any jobs removed for a partial release.
Next, submit the generated pending changelist manually.
After running this script, run package_downloads.sh
. This puts tar and zip files into the downloads folder. Submit the generated changelist manually.
# SDP Release Process Overview ## Introduction This document describes the process used to release the Server Deployment Package (SDP). This is intended for staff developing the SDP. ## Preparation A dedicated SDP workspace should be used for releasing the SDP, separate from any you might use for SDP development. This dedicated release workspace should not contain any cruft files such as editor temp files. The release process mechanisms prevents known-cruft files from being added such as *~ files and .DS_Store files on Mac. Using a clean dedicated release workspace guarantees no local excess files can sneak into the packaging process. ## Procedure ### Step 1: Develop! Develop and test changes in dev branch. This will occur over time. ### Step 2: Determine Release Type and Release Date Determine if the SDP release is to be Major, Patch, or Doc Only. Starting with the 2021.2 release of P4D, SDP major releases are tied to the P4D release schedule, **with SDP releases occuring when P4D releases, plus or minus no more than 2 business days**. Other releases will be Patch releases if there are any functionality changes, or Doc Only releases, where changes since the last release affect only documentation. The SDP documentation is key to its value, worth doing patch updates including only documentation changes. ### Step 3: Verify SDP Regression Tests Verify that the SDP regression test suite is successful. The SDP regression test suite is only accessible from the Perforce VPN. ### Step 4: Associate Jobs If not already done during development, create jobs and associate them with changelists in the `dev` branch, e.g. using `p4 fix -c <CL> SDP-<NNN>`. We don't need a job for every change. Create jobs to cover the essentials of what changed. Folks who want the gory details can look at changelists, but folks looking only at jobs should get a summary of what's new in this release or patch, and if appropriate, what to be aware of when taking this release. The first line of the job description will be incorporated into the release notes, so make the first line a good headline for the job. ### Step 4: Load Release Tools Load the latest SDP tools shell environment. Change to the dir in your SDP workspace corresponding to `//guest/perforce_software/sdp/tools`, and do `p4 -s sync` followed by `source ./env.sh` in that directory. ### Step 5: Merge Down Ensure the `dev` branch is updated from main. This ensures any hot fixes that my have been made directly in `main` branch are considered for incorporation in the formal release. ``` $ p4 merge -n -b perforce_software-sdp-dev All revision(s) already integrated. ``` If there is anything to merge, take care of it in your regular SDP development workspace, not the release workspace. If needed, file new jobs and associate them with changes. Upon completion of any needed merge work. ### Step 6: Update Doc Versions Update AsciiDoc `revnumber` and `revdate`. This step applies to major releases only; skip this for patch releases. In all *.adoc files, verify that the `:revnumber:` and `:revdate:` tags in the file refer to the correct SDP release version and date the file was last modified -- updating it to the current date. The fields look something like this example in each *.adoc file: ``` :revnumber: v2021.1 :revdate: 2021-10-20 ``` Review documents for any out-of-date references or content. ### Step 7: Generate Docs Ensure generated documentation is current. Run the `gen_script_man_pages.sh -submit` and observe the output. It may or may not create a new changelist in `//guest/perforce_software/sdp/dev/doc/gen/...`, depending on whether the underlying scripts have changed since they were last generated. ### Step 8: Generate Release Notes Run the `rel_notes.sh` script to update the Version and Release Notes files in the dev branch. (NOTE: If you are runnign this on Mac OSX, do a `brew install bash` first to get a modern version of bash, v4.x+, and then run `bash rel_notes.sh` to override the version of bash executed.) If the jobs listed in the generated release notes aren't complete enough, revert the `Version` and `doc/ReleaseNotes...` files, update the job descriptions, and try again. If this is a new major release, manually update the section, "What's New in <this version>". Summarize what to be aware of when taking this release, summarize what's in the release, and document details to be aware of when upgrading to this release. This script is interactive and prompts for the major version, e.g. 2020.1 (proposing as a default whatever the previous value was). It takes no command line arguments. It also prompts for the Release Type, e.g. GA or Patch. The `rel_notes.sh` wants your workspace to be clean, with the latest files sync'd, nothing checked out in the `dev` and `main` branches, and that a `p4 status` command reporting nothing to reconcile. ***WARNING***: If you need to do a partial release (i.e. if you need to hold some changes back in the `dev` branch), be sure to remove jobs referencing files you do not intend to promote. Note that partial releases are discouraged. ***WARNING***: If a partial release was done previously and files are now ready to be released, you'll need to add those jobs to the release notes manually. Doing a partial release will confuse the mechanism used in `rel_notes.sh` to determine what jobs were fixed since the last release, as it does a `p4 fixes` command in the dev branch looking for fixes since the last release changelist number in the Version file. Even a partial release updates the changelist number, and thus will require manual intervention to get the list of jobs correct. The `rel_notes.sh` script leaves the Version and Release Notes files checked out in a pending changelist for you to review. It also provides a list of commands to execute to complete the submit of the release notes. Submit that change manually when ready, e.g. after adding the "What's New in <this version>" content. Also, follow the guidance at the end of the output in the script about running the `make clean all` and `p4 rec` commands as directed in the output of the `rel_notes.sh` script. That tail end of that output should look something like this: ``` Executing: p4 edit -c 27821 //guest/perforce_software/sdp/dev/doc/ReleaseNotes.html //guest/perforce_software/sdp/dev/doc/ReleaseNotes.pdf //guest/perforce_software/sdp/dev/doc/ReleaseNotes.html#24 - opened for edit //guest/perforce_software/sdp/dev/doc/ReleaseNotes.pdf#25 - opened for edit Massage the release notes and changelist description as needed. Then do: cd /re/sdp/dev/doc make clean all p4 rec -c 27821 p4 -s submit -c 27821 ``` Follow those commands as instructed. These steps will ensure generated documentation is current with the latest *.adoc files. ### Step 9: Copy Up Push the files to main. Change to the `dev` branch directory in your workspace. Run `mdcu.sh` (Merge Down/Copy Up) script, which takes no arguments and is not interactive. That script creates a pending changelist with the Copy Up main. Massage the generated pending changelist description if desired. **WARNING FOR PARTIAL RELEASES**: If this is to be a partial release, revert any files that are not ready to be released from the main branch. Also be sure the reverted files correlate to any jobs removed for a partial release. Next, submit the generated pending changelist manually. ### Step 10: Package After running this script, run `package_downloads.sh`. This puts tar and zip files into the downloads folder. Submit the generated changelist manually.
# | Change | User | Description | Committed | |
---|---|---|---|---|---|
#24 | 30387 | C. Thomas Tyler | Updated SDP release process notes. | ||
#23 | 30358 | C. Thomas Tyler | Cleaned up notes about updating regression test suite for major versions. | ||
#22 | 30338 | C. Thomas Tyler |
Updated release process overview to account for changes needed to P4*.json release list files for each major release. |
||
#21 | 30293 | C. Thomas Tyler | Added new steps to udpate SDP Version file. | ||
#20 | 30111 | C. Thomas Tyler | Accounted for move of gen_script_man_pages.sh to SDP package tree. | ||
#19 | 30005 | C. Thomas Tyler | Refined slightly. | ||
#18 | 29835 | C. Thomas Tyler |
Updated Release Process to account for migration to JIRA. Removed scripts made obsolete by this change to avoid confusion. |
||
#17 | 29234 | C. Thomas Tyler |
Updated release process doc with note about updating test suite to use latest SDP for major releases, and added details. Fixed order bug. |
||
#16 | 29202 | C. Thomas Tyler | Fixed doc typo. | ||
#15 | 28653 | C. Thomas Tyler | Updated SDP release process docs. | ||
#14 | 28615 | C. Thomas Tyler | Documented new required steps in the SDP Relase Process. | ||
#13 | 28107 | C. Thomas Tyler | Replaced PRE tags with tripple-backticks for proper rendering. | ||
#12 | 28106 | C. Thomas Tyler | Text tweaks. | ||
#11 | 28105 | C. Thomas Tyler | Updated SDP Release Process. | ||
#10 | 27842 | C. Thomas Tyler | Minor updates to improve clarity of SDP release process overview doc. | ||
#9 | 27525 | C. Thomas Tyler | Tweaked notes to account for running on Mac, etc. | ||
#8 | 27465 | C. Thomas Tyler | Updated release notes. | ||
#7 | 27461 | C. Thomas Tyler | Refined AsciiDoc generated doc update part of release process. | ||
#6 | 27323 | C. Thomas Tyler | Tweaked release process doc. | ||
#5 | 27314 | C. Thomas Tyler | Refined release process overview notes. | ||
#4 | 27115 | C. Thomas Tyler |
Updated SDP release process doc, adding info on how to ensure generated script docs are incorporated in AsciiDoc files. Adjusted generated release notes file from .txt to .adoc format. Updated rel_notes.sh to add bulleted list items with links to each fixed job. Updated old release notes content to use new format (using disposable link conversion scripts). |
||
#3 | 24397 | C. Thomas Tyler | Tweaked SDP release process overview notes. | ||
#2 | 21524 | C. Thomas Tyler | Updated release process overview. | ||
#1 | 20479 | C. Thomas Tyler |
Added release process overview script. Overhauled release notes helper script. Fixed bug that listed a job in the release notes for the current release that was associated with the last changelist of the prior release. Updated more of the manual steps in the SDP release process. |