Developer Guide

Robert Bouillon (Slack/e-mail) is the technical lead for this project, managing the architecture and technical development.

Donna Fiorenza is the project lead, managing the priority and scope of ongoing development.

Development efforts are coordinated via bi-weekly zoom meetings. Please contact Greg Wong if you would like to participate. The regular meetings include stakeholders from various parts of the organization.

Development Environment

Requirements

  1. Visual Studio 2022

  2. GIT

  3. .NET 7.0

  4. Node.js

  5. Python (For Sphinx Documentation)

  6. VS Code (For Sphinx documentation)

    • ESLint

    • MyST-Markdown

    • reStructuredText

  7. Powershell 7

    • Import-Module AWS.Tools.S3

Setting up the local environment

  1. Install GIT for Windows

  2. Install Visual Studio 2019 with .NET Desktop development roles.

  3. In Visual Studio, create a new project from GitHub using https://github.com/usspeedskating/tempus.git

  4. In Visual Studio, import the Assets\Development\Tempus.vssettings configuration from withing the repo. This will reconfigure your window layout, including two terminal windows which will be used frequently during development.

  5. Add a new Terminal to the Developer Terminal window a. Click the Settings button (the gear) in the terminal window b. Click the Add button to add a new terminal c. Change the Name field to “Project PowerShell” d. Change the Arguments field to -NoExit -Command "& { Import-Module $env:VSAPPIDDIR\..\Tools\Microsoft.VisualStudio.DevShell.dll};  if (Test-Path .\utils.ps1) { . .\utils.ps1 }; Enter-VsDevShell -SkipAutomaticLocation -SetDefaultWindowTitle -InstallPath $env:VSAPPIDDIR\..\..\. e. Click the Apply button. f. Click the Set as Default button.

  6. Restart Visual Studio and open the Tempus Project

  7. Click in the terminal window, type pull, and press enter to pull all the submodules.

Running the Application

Web Interface

  1. Open the project in Visual Studio

  2. Ensure that the build configuration is set to Debug

  3. Type watch in the Developer Powershell window and press enter to run the application locally and begin debugging.

  4. A browser window will open with the application

Local Client

  1. Open the project in Visual Studio

  2. Ensure that the build configuration is set to Debug

  3. Type watch in the Developer Powershell window and press enter to run the application locally.

  4. Right-Click the TempusChromely project and select Set as Startup Project

  5. Press F5 to begin debugging.

In DEBUG, the local client will point to the development webserver - localhost:5001. In RELEASE, the local client will point to the local cache in the bin\tempus folder.

Contributing

To contribute, follow the GitHub instructions for pull requests.

All pull requests should be associated with an issue in the tempus-public repository. All pull requests will undergo code review by the admins prior to being integrated.

Coding Guidelines

Please follow the existing coding patterns. Some notable specifics:

  1. All indents (tabs) must be set to two spaces.

  2. Do not submit changes that only reformat code unless it’s associated with an approved work-item

C#

  • ISerializable implementation MUST be explicit unless they are overriding a member of a derived class that implements ISerializable

  • Serialization members should be wrapped in a region entitled “Serialization”

  • USS.Tempus.IO SHOULD only be referenced by a relative IO, when possible. AVOID adding USS.Tempus.IO as a using and AVOID absolutely prefixing classes from that namespace. PREFER to add using USS.Tempus; with relative references to classes in IO.

Debugging

The best way to debug an issue in the competition logic is to create a unit test in the associated class and run the Test Harness. This is because the WASM debugger is still incomplete, buggy, and slow. To get the best debugging experience, you want to run the code in a full .NET environment.

A common approach is to create a test file in Excel (or reuse one) and import it from the Assets\Test Cases directory as part of the unit test.

There’s currently not automation framework for debugging UI issues, and the WASM debugger is your only option.

Deploying

For most changes, you only need to deploy Tempus and the Documentation. The installer only needs to be deployed if it was updated.

Deploying a new version of Tempus

  1. Run the automated tests test-tempus

  2. Bump the version using bump-version

  3. Build the version using build-tempus

  4. Publish the version using deploy-tempus

  5. Test the latest version in the virtual machine

Rollback Deployment

To roll back a deployment, set the latest version to the previous known good version using set-version N.N.

Deploying the documentation

  1. Publish the documentation using deploy-docs

Deploying the Installer

  1. Build the version using build-installer

  2. Publish the version using deploy-installer

Testing the Deployment

  1. Open up the Virtual Machine for testing.

  2. Install & Run the application from https://tempus.usspeedskating.org/

  3. Ensure the version number is correct

  4. Revert changes to the virtual machine