From 09e2815208c6a2237568a4689ced03ae5b43b0b7 Mon Sep 17 00:00:00 2001
From: Niko Ehrenfeuchter <nikolaus.ehrenfeuchter@unibas.ch>
Date: Tue, 23 Apr 2019 16:56:40 +0200
Subject: [PATCH] Document build-deploy-update cycle through helper scripts
Fixes #65
---
CONTRIBUTING.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 75 insertions(+)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d75cc84..ea85c1e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -67,6 +67,81 @@ Refactoring suggestions and / or pull requests are welcome!
reference that issue in the commit message (issue tracking is done in the
[primary repository in the Uni Basel GitLab][web_autotx_gitlab]).
+## The Full Cycle: Change / Compile / Package / Update / Test
+
+To run a typical development cycle, a few helper scripts are provided, most
+notably to facilitate / automate that cycle whilst using the common
+functionalities coming with AutoTx (like the updater).
+
+### Building / Compiling
+
+Open a shell session using the `Developer Command Prompt for VS 2017` shortcut
+(doesn't require any special permissions, i.e. can be your user that's also
+running Visual Studio). For convenience reasons it is recommended to start
+`PowerShell` within this terminal, but this is not strictly required. Navigate
+to the `AutoTx` source code base directory, then call any of the `.cmd` scripts
+under `Scripts/msbuild` depending on your needs. For a *Debug* build this would
+be something like this:
+
+```PowerShell
+cd C:\Devel\AutoTx ## <- adjust path to your requirements
+.\Scripts\msbuild\build\debug.cmd
+```
+
+### Creating an Installation / Updater Package
+
+After building the service has completed, use the `Deploy-NewBuild.ps1` script,
+optionally with specifying the path to the updater configuration (by default
+the script will assume "`C:\Tools\AutoTx-Updater\UpdaterConfig.inc.ps1`" for
+this).
+
+```PowerShell
+.\Scripts\Deploy-NewBuild.ps1
+# or by specifying the config explicitly:
+.\Scripts\Deploy-NewBuild.ps1 -UpdaterSettings C:\Path\To\UpdaterConfig.inc.ps1
+```
+
+Running this should produce output similar to the one shown here:
+
+```
+Creating package [build_2019-04-23_14-14-42__3.0-70-gf90a55c] using binaries from:
+ [C:\Devel\AutoTx\ATxService\bin\Debug]
+ [C:\Devel\AutoTx\ATxTray\bin\Debug]
+ [C:\Devel\AutoTx\ATxConfigTest\bin\Debug]
+ [C:\Devel\AutoTx\ATxDiagnostics\bin\Debug]
+
+Removing existing package dir [build_2019-04-23_14-14-42__3.0-70-gf90a55c]...
+
+Done creating package [build_2019-04-23_14-14-42__3.0-70-gf90a55c]
+ [configuration: Debug]
+ [commit: 3.0-70-gf90a55c]
+
+Location: [C:\Devel\AutoTx\Scripts\build_2019-04-23_14-14-42__3.0-70-gf90a55c]
+```
+
+### Triggering the Updater
+
+Running the updater can be done in various ways, for example you could simply
+call the script manually from a PowerShell session with sufficient privileges.
+However, the recommended method is to actually trigger the scheduled task to
+mimick a "*real-life*" run as closely as possible. This is doable using the
+GUI (e.g. by launching `compmgmt.msc` and clicking all your way through the
+"Task Scheduler" tree jungle). A much easier approach is to use the command line
+again to run the job. Unfortunately there is no *straightforward* way to launch
+a registered job on Windows 7 (on Windows 10 there is the `Start-ScheduledTask`
+cmdlet), so you have to take a little detour. First of all make sure to have a
+PowerShell session running with *elevated privileges* (i.e. it is **not enough**
+to run it with an administrator account, you explicitly need to start it with
+the "Run as Administrator" option), then issue this command:
+
+```PowerShell
+(Get-ScheduledJob -Name "AutoTx-Updater").StartJob()
+```
+
+This should trigger a run of the updater, any actions will be recorded to the
+Windows Event Log. In case the service was running before, it will be restarted
+and show its related messages in the service log file.
+
## Coding Conventions
As mentioned above, the **C#** style used throughout the project differs from
--
GitLab