Skip to content

Latest commit

 

History

History
159 lines (118 loc) · 6.2 KB

DEVEL.md

File metadata and controls

159 lines (118 loc) · 6.2 KB
Raw

SolarMonitor Build Instructions

Summary

  • Restore deps: dotnet restore (in the root dir.)
  • Build all (F7): build/build_all.sh (Runs dotnet build in the root dir.)
  • Unit tests (F8): build/run_unit_tests.sh (Runs dotnet test in each test dir.)
  • Run in debugger: Select ".NET Core Launch" + F5
  • Run tests in debugger: Select "Debug unit tests (...) + F5
  • Run API container: build/docker_run_webapi.sh <version> (Instantiates pre-built Web.API image and runs resulting container. Cleans up afterwards.)

Build requirements

  • dotnet command version 2.0.0 or newer. Note: this version is based on msbuild and is able to build csproj project files.
  • monodis from the mono package is needed for checking assembly versions.
  • The build uses .NET Core 2.0 (Note: build dependencies are resolved automatically by dotnet restore command).

Branching and versioning strategy

Versioning

  • Version string format: <major_version_number>.<minor_version_number>.<release_number>.<build_number>
    • major_version_number and minor_version_number are always changed during a release (usually only the minor number) e.g. 0.1.0 (master) -> 0.2.0 (rel-0.2.0), 0.3.0 (master) , or 1.7.0 (master) -> 2.0.0 (rel-2.0.0), 2.1.0 (master)
    • If after a release major bug fixes are required for an already released version, we'll use the patch_number to create a new release e.g. 0.2.0 (rel-0.2.0) -> 0.2.1 (rel-0.2.1)
    • The build_number is generated by Jenkins for each build. This starts at 0 for new branches.
  • The minor version number of a branch must be even, while on master, it's always odd

Branching

  • Stable branches are created at release time and must be named rel-<version-string>, e.g. rel-0.2.0
  • Stable branches get their versions from the branch name e.g. branch rel-0.2.0 will be versioned as 0.2.0.<build_number>
  • Any other branch (e.g. feature branches, temporary development branches, etc) can have any name and will be versioned 0.0.0.<build_number>
  • Branching is performed when the master reaches a point which is deemed ready for a release (i.e. it contains the required features and it reached a certain level of stability)
  • Preparing for a release:
    • create a new branch, rel-0.2.0:
      • git checkout -b rel-0.2.0
      • git push origin rel-0.2.0
    • update version string on the master branch in Jenkinsfile by updating the VERSION_STRING_DEFAULT variable at the top of the file:
      • def VERSION_STRING_DEFAULT = "0.3.0"
      • the new version should be: <branch_version> + 0.1.0
      • Note: make sure the change to Jenkinsfile is pushed to master

Useful tools

git commands

Log:

  • git lg -5 (alias for git log --pretty=oneline)

Pulling:

  • git pl (alias for git pull --rebase --tags)

Branching:

  • git checkout -b rel-0.2.0
  • git push origin rel-0.2.0

Cherry-picking (master -> rel-0.2.0):

  • git checkout master
  • git lg -5
  • git checkout rel-0.2.0
  • git cherry-pick <commit3> <commit2> <commit1> (Note: commits must be in reverse order)
  • git push
  • git checkout master

Reverting:

  • git revert <commit>

"dotnet ef" commands

Note: dotnet ef commands must be run in the main SolarMonitor.Web.Api project folder. The project must have the EF tools referenced in project.json. Currently there is a limitation meaning that only NetCoreApp projects support running ef commands (i.e. no supporting libraries).

  • Migrations:

    • $ dotnet ef migrations list (List current migrations, found in ./migrations folder)
    • $ dotnet ef migrations add migration1 (Add a new migration containing changes to the db schema from the previous migration) Note: migrations are found in ./migrations. To start again, delete this folder.
    • $ dotnet ef migrations script -o SolarMonitorDbSchema.sql (Save all migrations into a SQL script with the full schema)

  • Database updates:

    • $ dotnet ef database update (Apply any missing migrations to the database.)

Azure CLI commands

Prerequisites

  • Azure CLI tool:
    • $ sudo npm install azure-cli -g

Main commands

  • Set the account details:

    • $ azure account download
    • $ azure account import ./downloads/Pay-As-You-Go-8-4-2016-credentials.publishsettings

  • List azure sites:

    • $ azure site list
    • $ azure site show solarmonitor-test
    • $ azure site show solarmonitornz

  • Set new deployment branch (Note: this does not currently work):

    • $ azure site repository branch rel-0.2.0 solarmonitor-test
    • The way we do it now is by editing /site/deployment/settings.xml on https://solarmonitor-test.scm.azurewebsites.net (use the Kudu portal -> Debug console or Filezilla to upload file directly)

Managing user secretes with "dotnet user-secrets"

Secrets are managed with dotnet user-secrets command. They are stored by the tool (automatically) in ~/.microsoft/usersecrets/SolarMonitorSecrets/secrets.json.

  • Adding new secret: ** Commands must be run in src/SolarMonitor.Web.Api (since the tool has only been configured in this project) ** dotnet user-secrets set <NewKey> <NewValue>

  • List secrets: ** dotnet user-secrets list

  • The secrets can then be accessed in the code via Configuration["NewKey"]

  • Note: the SolarMonitor.Web.Api.csproj has been configured for the Secret Manager tool as follows:

    • UserSecretsId property was set:
    <UserSecretsId>SolarMonitorSecrets</UserSecretsId>
    • The tool was added to the project:
    <DotNetCliToolReference Include="Microsoft.Extensions.SecretManager.Tools" Version="1.0.1" />