Development Flow - pc2ccs/pc2v9 GitHub Wiki

All PC2-related projects are maintained in Git repositories. This article describes how a fix or new feature is added to a project in PC2.

The process of making a change (a code fix or an enhancement) to PC² involves a series of steps, most of which are performed by the developer proposing the change. In general the steps are as follows:

• Create a GitHub account if you don't already have one.

• Create a GitHub fork of the PC2v9 Git repository. A fork can be created by going to the PC2v9 GitHub repository and clicking the Fork icon in the upper right corner. This fork becomes a "copy" of the PC2v9 repo; the fork resides in your account on the GitHub site and is implicitly linked to the PC2v9 repository (that is, the PC2v9 repository is the "origin" repo for your fork).

• Clone your fork of the PC2v9 GitHub repository onto your local machine (we call this the local Git repo). Your fork can be cloned onto your local machine either by using Git commands in a shell (command-line interpreter) or using a cloning tool with an IDE such as Eclipse.

  • The general form of the clone command to be typed at a command prompt will look like:git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY, where you substitute your GitHub User Name and repository fork name into the command.
  • A handy way to avoid typos in the command is to go to your GitHub fork, press the "Clone or Download" button, and then press the little "Copy to clipboard" icon. This copies the correct URL for your fork to your clipboard; you can then go to a command prompt on your local machine and enter git clone followed by ^V to paste the URL onto the command. (Note that the GitHub Clone or Download button provides the option of copying HTTPS or SSH with GIT protocol forms of the URL.)
  • To use Eclipse to clone your fork, use the Clone a Git Repository icon in the Git Repositories "view" (this assumes you have installed the Eclipse Egit plugin).

  Regardless of which approach you use to clone your fork, your local Git repo (clone) will have your GitHub fork as its "origin" repo. See this page for additional information about cloning GitHub repos.

• Configure the PC2v9 repository as the "upstream" repository for your clone. (The term "upstream" here refers to the repository which is upstream from the origin repository -- that is, the repository which is the "origin repo for your clone's origin repo".) Setting the "upstream" for your clone allows you to keep your clone and your fork in sync with changes which may occur in the PC2v9 Git Repository. Note the following with respect to configuring the upstream repository:

  • The command-line instruction to set the upstream for your local clone is git remote add upstream https://github.com/pc2ccs/pc2v9.
  • In Eclipse, setting the upstream can be done by right-clicking on the local repository in the Git Repositories view, clicking Properties, and using the Add Entry button to add new entries for remote.upstream.fetch and remote.upstream.url (which is exactly what the above command line does).
  • The Eclipse Egit Git plugin sometimes uses the term upstream to refer to the origin repository. (For example, the Eclipse Egit menu item "Push to Upstream" actually means "push to origin".) Do not confuse this usage of the term upstream with the upstream remote being added to your clone in this step.
  • See this page for additional information about configuring upstream repositories for forks.

After completing the above steps you will have a local Git repo which has your GitHub fork as its "origin", where your GitHub fork has the PC2v9 main repository as its "origin" repo, and where your local clone has the PC2v9 main repo as its "upstream". Typically, development work is done in the local Git repo and then pushed back up to your fork, followed by submitting a Pull Request (see the instructions below for details).

• Insure there is a bug (issue) report for the work filed in the PC2V9 Git Issues.

• Sync your fork with the upstream repository. This updates both your local repo and your GitHub fork with any changes which have been made in the original PC2v9 repository; this should be done periodically to insure that your fork remains up-to-date. (Note that the preceding link talks about sync'ing with the master branch, which is not something you should do; PC2v9 local clones and GitHub forks should be sync'd with the develop branch.) The steps to sync your fork with the upstream repo are:

  • Fetch the branches and their respective commits from the upstream repository into your local clone: git fetch upstream
  • Check out the develop branch in your local clone: git checkout develop
  • Merge the changes from the upstream/develop branch into your local develop branch: git merge upstream/develop
  • Push the updated local repo up to your PC2v9 GitHub fork: git push.

• Create an issue branch in your local Git repo for doing the development work, and switch to that branch.

  • The command-line statement for creating and switching to ("checking out") a new branch is: git checkout -b branchName.
  • In Eclipse (with Egit installed) this can be done by right-clicking on the project and selecting Team > Switch To > New branch and entering the branch name. You should also check the boxes "Check out new branch" and "Configure upstream for push and pull" (recall from above that Egit references to "upstream" are actually references to "origin").

  Branch names should be of the form i_issue#_issue_description. See Development Standards regarding further guidelines for naming PC2v9 branches; see Development Policies and Procedures for additional details on working on issue branches.

• Develop your code change(s) on the issue branch in the local Git repo (for example, using an IDE such as Eclipse). See Development Standards and Development Environment for guidelines on developing code for PC2v9.

• Test your code changes, by writing and running JUnit tests. JUnit tests should be located in the ./test folder, under the appropriate Java package.

• Run all existing PC2v9 JUnit tests (these will automatically present in your local repo by virtue of the fact that you forked and cloned the PC2v9 repo). In Eclipse, the PC2v9 JUnits can be run by right-clicking on the test folder and selecting RunAs > JunitTest.

• Build a PC² distribution (see Building a PC2 Distribution), copy the distribution file to a clean folder (and/or onto multiple machines as necessary for testing), unzip the distribution, and run a "smoke test" to verify that the distribution as built with your changes works correctly. (That is, start a PC2 Server, configure it with a contest (either interactively using an Admin or via YAML Contest Configuration files), and verify that the PC² Admin, Team, Judge, and other clients as necessary work properly with your changes.) Note that the samps/contests folder contains numerous pre-configured contests which can be used for "smoke testing".

• Commit the code changes on the issue branch to the local Git repo. (Note: it is common, and frequently desirable, to do a series of incremental commits rather than waiting until everything is working; development is typically an iterative process involving repeated execution of the above steps.)

This step is necessary because the develop branch might have been updated between the time you last sync'd your repos (local and fork) with the PC2v9 code stream. It is important to verify that your code works with the latest develop branch; otherwise a Pull Request for your code is almost certainly going to be rejected.

• Follow the instructions above under Sync your fork with the upstream repository to insure your local repo and your fork are up to date. Be sure to note that the above instructions include switching to the develop branch before doing the sync. The steps to do this (from above) are:

git fetch upstream
git checkout develop
git merge upstream/develop

• After sync'ing as described above, switch back to your issue branch: git checkout i_issue#_issue_description.

• Rebase your branch onto the tip of the develop branch: git rebase develop. Rebasing moves the commits which you have made on your issue branch so that they are effectively applied "on top of" any changes which have occurred in the PC2v9 code stream (effectively, it unwinds your commits, applies any new commits from the develop branch, and then reapplies your commits on top of that). This is how you verify that your changes are compatible with the latest PC2v9 code.

• Fix any merge conflicts. (Merge conflicts mean that there is something about your code which is incompatible with the latest PC2v9 develop branch; these issues must be fixed before you can submit your code.) See this page for insights into resolving merge conflicts.

• Test again that all your code updates are working correctly.

  • Rerun all of your JUnit tests.
  • Rerun all of the existing PC2v9 JUnit tests.
  • Build a new distribution and run another "smoke test" on it.

Note: Do not merge your issue branch into either your local repo's "master" or "develop" branch; this will cause your Pull Request to be rejected. (Merging is not the same thing as the rebasing done above.)

• Make sure you are still on the issue branch (NOT on the "develop" branch) in your local repo (or git checkout i_issue#_issue_description to be sure).

• Push the issue branch from your local Git repo to your GitHub fork: git push --force. (The --force is to deal with any changes that happened because of the rebasing done above).

• Go to the GitHub page for your fork.

• On the "Code" tab, locate your pushed branch and click Compare & pull request.

• Click the base:master dropdown and select develop.

• Fill in the PR template. See Guidelines for Submitting Pull Requests for additional details.

• Click Create Pull Request.

See Creating a Pull Request (PR) for additional details about GitHub Pull Requests.

At this point the PC2 project maintainers will examine your PR and decide whether to accept it (i.e., to merge it into the PC2v9 code stream), or to provide feedback on the PR, or to reject it. In any case you should at least receive some feedback from the PC2 Development Team.

If the PR is accepted and merged into PC2v9, it causes the Continuous Integration and Deployment (CI-CD) automated build system to generate a new "distribution" (also referred to as a "build"). Once a new distribution has been generated it must be downloaded from the [https://pc2.ecs.csus.edu/pc2tug/builds/v9.allbuilds.php PC2 Builds Page] and tested for correctness.

• PC2 Developer's Notes
• Development Environment
• Development Standards
• Development Policies and Procedures
• Guidelines for contributing to PC2
• Building a PC2 Distribution