Building a PC2 Distribution - pc2ccs/pc2v9 GitHub Wiki

Overview

A distribution in PC² terminology refers to a single package, normally either a .zip or .tar.gz file, which holds a complete self-contained PC² system. A distribution file can be copied to a different computer (or multiple computers) and, when unzipped provides all of the code and data files necessary to run a PC² module (e.g. a Server, Team, Judge, Scoreboard, etc.) on that machine.

PC² distributions come in two types: local builds and public releases. A local build is a distribution which is created on a developer's machine, usually for testing purposes. Like all distributions, a local build distribution contains the complete PC² system; it can be copied to multiple machines and will allow executing any PC² module wherever it is copied. However, because it is built on a developer's machine, it may (likely will) contain libraries and other features which are specific to that developer's machine. For this reason, local builds should not be used for anything other than testing (typically by the developer who created it).

Public releases are distributions which are automatically created by the PC² Continuous Integration and Deployment (CI CD) process. They are automatically posted on the PC² web page and are available for public download.

Local Builds

The PC² development system includes an Ant script named package.xml which can be used to create a complete PC² build. The script includes invocations of additional scripts to build all PC2 Projects (for example, the Web Team Interface (WTI) project, described at Web Access). When the package.xml script completes, the dist folder under the pc2v9 project will contain (among other things) .zip and .tar.gz local-build distributions. In addition, each PC² subproject will contain a dist folder holding distribution files (again, .zip and .tar.gz) containing that subproject.

Note: PC² distributions normally include a "Build Number" as part of the distribution file name. Since a local build cannot know what public distribution number it might correspond to, package.xml generates a locally-specific build number and uses that in the distribution file names.

Public Builds

Whenever an update is made to either the develop branch or the master branch in the main PC² repository, it triggers an automatic invocation of the Continuous Integration and Deployment (CI CD) cycle. Assuming the CI/CD cycle completes successfully, the result includes creation of a new PC² public build. (The CI/CD cycle also generates other artifacts, including updates to the PC² web page; see the CI/CD Wiki page for details.)

If the update was on the develop branch, the resulting distribution is posted to the PC² web page as a (publicly-available) Nightly Build. (This is perhaps a slight misnomer, as the builds don't happen "nightly" but rather whenever an update is pushed to develop.) If the update was on the master branch, the resulting distribution is posted on the PC² web page as a (publicly-available) Release Candidate. In either case the build number is increased monotonically.

Release Candidate distributions can be promoted to stable public releases; the process for doing this is as follows:

Ensure that all the changes intended to be part of the Stable Public Release have been merged to master (so that they are contained in the current "Release Candidate").
- Note in particular that if a Release Candidate is to be promoted to a new Stable Public Release, it should contain an updated copy of the PC2V9 Contest Administrator's Guide. The master copy of the Admin Guide resides in the folder doc/src, in the file pc2v9AdminGuide.docx. To generate a new Admin Guide, this file must be edited as necessary and then a new PDF must be generated and saved in the doc folder.
- However, doing this does not update the copy of the Admin Guide which is referenced by the Documentation: Contest Administrator's Guide (PDF) link on the website Home Page. Rather, that link automatically references whatever copy of the document is currently stored under website/static/docs (in the pc2v9 repo). Therefore, when a new Stable Public Release is to be generated, the updated copy of the Admin Guide should first have been copied into website/static/docs and merged into the develop branch (which should then be merged in the master branch) prior to performing the following steps.
Go to https://github.com/pc2ccs/builds/releases.
If not already logged in, login to GitHub using an account which is authorized to make changes to the pc2ccs/pc2v9 repository.
Find the Release Candidate to be promoted to Stable Public Release, and click the Edit button
Scroll down and UNCHECK the "Set as a pre-release" checkbox.
Click "Update Release".
In your local Git repo, on the develop branch, edit the file build.xml in the PC2v9 source folder:
- Find the line <property name="version" value="9.xxbuild"/> (where xx is whatever the current build number is).
- Update that line by increasing the value of xx by one (let's call this new value yy), then save the updated file.
Submit a Pull Request for the changed build.xml file.
Merge the PR into develop. The merge will trigger a new CI/CD build cycle, which in turn will update the PC2 github.io webpages to show what was previously listed as the Release Candidate now as a Stable Release, with no current Release Candidate, and a "nightly build" with the updated build number as the "develop" branch. Any subsequent merges to develop will acquire the new "9.yybuild" version number reflected in the updated build.xml file.
Allow sufficient time for the new build to complete (typically ~10 minutes or so).
Go to the main PC2 website (https://pc2ccs.github.io/), refresh the page, and verify that
- The new "Stable Public Release" shows the correct build number.
- There is no "Release Candidate" listed.
- The "Nightly Build" shows the last push to Develop, with the "9.yybuild" number on it.