Update README and workspace configuration

ProjectTemplate.code-workspace

@@ -10,13 +10,17 @@
             "davidanson",
             "dotnettools",
             "dryrun",
+            "gpgsign",
             "gruntfuggly",
             "logfile",
             "nektos",
             "Nerdbank",
+            "Pieter",
             "ProjectTemplate",
             "Serilog",
+            "signingkey",
             "slnx",
+            "Viljoen",
             "winget",
             "xunit",
             "yzhang"
@@ -46,14 +50,14 @@
 	},
 	"extensions": {
 		"recommendations": [
+            "csharpier.csharpier-vscode",
             "davidanson.vscode-markdownlint",
-            "gruntfuggly.todo-tree",
-            "streetsidesoftware.code-spell-checker",
             "editorconfig.editorconfig",
-            "csharpier.csharpier-vscode",
             "github.vscode-github-actions",
+            "gruntfuggly.todo-tree",
             "ms-azuretools.vscode-docker",
             "ms-dotnettools.csdevkit",
+            "streetsidesoftware.code-spell-checker",
             "yzhang.markdown-all-in-one",
 		]
 	}

README.md

@@ -20,43 +20,51 @@ Packages published on [NuGet](https://www.nuget.org/packages/ptr727.ProjectTempl
 
 ## Developer Environment Setup
 
-- [Register](https://github.com/settings/keys) SSH Key on GitHub.
+### Tools Setup
 
-  ```shell
-  ssh-keygen -t ed25519 # If not already created
-  cat ~/.ssh/id_ed25519.pub
-  ssh-keyscan github.com >> ~/.ssh/known_hosts
-  ssh -v -T git@github.com
-  ```
+- Install VSCode and / or Visual Studio
+
+### Git Setup
 
-- Add [SSH keys to GitHub](https://github.com/settings/keys), add both an authentication and a signing key.
-- Configure git for [SSH signing](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key):
+- Configure Git options:
 
   ```shell
   git config --global credential.helper "cache --timeout=3600"
   git config --global user.name "Pieter Viljoen"
   git config --global user.email "ptr727@users.noreply.github.com"
   git config --global core.sharedRepository group
   git config --global --add safe.directory '*'
+  git config --list --show-origin
+  ```
+
+- [Register](https://github.com/settings/keys) SSH key for Authentication and Signing on GitHub.
 
+  ```shell
+  ssh-keygen -t ed25519 # If not already created
+  cat ~/.ssh/id_ed25519.pub # Paste into GitHub
+  ssh-keyscan github.com >> ~/.ssh/known_hosts
+  ssh -v -T git@github.com
+  ```
+
+- Configure Git for [SSH signing](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key):
+
+  ```shell
   git config --global gpg.format ssh
-  cat ~/.ssh/id_ed25519.pub
   git config --global user.signingkey "~/.ssh/id_ed25519.pub"
   git config --global commit.gpgsign true
   git config --global tag.gpgsign true
-
-  git show --show-signature # error: gpg.ssh.allowedSignersFile needs to be configured and exist for ssh signature verification
   mkdir -p ~/.config/git
-  touch ~/.config/git/allowed_signers
-  git config --global gpg.ssh.allowedSignersFile "~/.config/git/allowed_signers"
   echo "$(git config --get user.email) namespaces=\"git\" $(cat ~/.ssh/id_ed25519.pub)" >> ~/.config/git/allowed_signers
-  cat ~/.config/git/allowed_signers
-  git log --show-signature # Good "git" signature for ptr727@users.noreply.github.com with ED25519 key SHA256:[secret]
-
+  git config --global gpg.ssh.allowedSignersFile "~/.config/git/allowed_signers"
+  git log --show-signature
   git config --list --show-origin
   ```
 
+### Project Workspace Setup
+
 - New project:
+  - Create new project directory.
+  - Copy and rename template projects.
 
   ```shell
   git init
@@ -68,30 +76,50 @@ Packages published on [NuGet](https://www.nuget.org/packages/ptr727.ProjectTempl
   dotnet husky add pre-commit -c "dotnet husky run"
   ```
 
-- New deployment:
+- New pull of existing project:
 
   ```shell
   dotnet tool restore
   dotnet husky install
   chmod +x ./.husky/pre-commit # Make sure file is executable in Linux
-  winget install nektos.act # Windows optional
   ```
 
-- Update tools:
+- Update tools in existing project:
 
   ```shell
   dotnet tool update --all
   dotnet outdated --upgrade:prompt
-  winget upgrade nektos.act # Windows optional
   ```
 
-- Linux file modes:
-  - `chmod +x [filename.sh]`
-  - All shell files are `LF` mode.
+- Linux / macOS:
+  - Verify that shell files are `+x` executable and `LF` line ending mode.
+  - Verify that there are no duplicate files with different case names.
+
+### GitHub Local Actions Setup
 
-## Secrets Setup
+- Install [ACT](https://nektosact.com/installation/index.html):
 
-- Create a [Nuget API Key](https://www.nuget.org/account/apikeys).
+  ```shell
+  winget install nektos.act
+  winget upgrade nektos.act
+  ```
+
+- Install [VSCode extension](https://sanjulaganepola.github.io/github-local-actions-docs/).
+- Update [settings](https://nektosact.com/usage/index.html#action-artifacts) to start the artifact server.
+
+  ```json
+  "githubLocalActions.actCommand": "act --artifact-server-path ./.artifacts",
+  ```
+
+- Update local secrets:
+  - Save the existing [Docker Hub Personal Access Token](https://app.docker.com/accounts/ptr727/settings/personal-access-tokens) as `DOCKER_HUB_ACCESS_TOKEN` and `DOCKER_HUB_USERNAME`.
+  - Create a [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens) as `GITHUB_TOKEN`.
+
+## GitHub Setup
+
+### GitHub Secrets Setup
+
+- Create a [NuGet API Key](https://www.nuget.org/account/apikeys).
   - Save the Key as `NUGET_API_KEY` in:
     - GitHub project security Settings / Secrets / Actions.
     - GitHub project security Settings / Secrets / Dependabot.
@@ -100,43 +128,47 @@ Packages published on [NuGet](https://www.nuget.org/packages/ptr727.ProjectTempl
   - Save the PAT as `DOCKER_HUB_ACCESS_TOKEN` and `DOCKER_HUB_USERNAME` in:
     - GitHub project security Settings / Secrets / Actions.
     - GitHub project security Settings / Secrets / Dependabot.
-    - GitHub Local Actions Settings / Secrets.
-- Create a [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens).
-  - Save the PAT as `GITHUB_TOKEN` in:
-    - GitHub Local Actions Settings / Secrets.
 
-## GitHub Local Actions Setup
-
-- Update [ACT settings](https://nektosact.com/usage/index.html#action-artifacts) to start the artifact server `act --artifact-server-path ./.artifacts`.
-
-## GitHub Project Settings
+### GitHub Project Settings
 
 - General:
-  - Set the default branch to `main`.
-  - Enable `Always suggest updating pull request branches`.
-  - Enable `Allow auto-merge`.
-  - Enable `Automatically delete head branches`.
-- Rules / Branch Ruleset:
-  - `main`:
+  - Default branch: `main`
+  - Pull requests:
+    - `Allow squash merging`
+    - `Always suggest updating pull request branches`
+    - `Allow auto-merge`
+- Rules / Rulesets:
+  - "Main and Develop":
+    - Target branches: `main`, `develop`.
     - `Restrict deletions`
     - `Require linear history`
     - `Require signed commits`
     - `Require a pull request before merging`
       - `Dismiss stale pull request approvals when new commits are pushed`
+      - Allowed merge methods: `Squash`
     - `Require status checks to pass`
       - `Require branches to be up to date before merging`
-      - `Require branches to be up to date before merging`
-      - Add checks: `Check pull request workflow status`
+      - Status checks that are required: `Check pull request workflow status`
     - `Block force pushes`
     - `Automatically request Copilot code review`
-  - `develop`:
-    - `Restrict deletions`
-    - `Require linear history`
-    - `Require signed commits`
-    - `Automatically request Copilot code review`
+      - `Review new pushes`
+      - `Review draft pull requests`
 - Actions / General:
   - `Allow GitHub Actions to create and approve pull requests`
 
+## Branching Workflow
+
+- Create persistent `main` and `develop` branches.
+- Make sure that `main` and `develop` are always building.
+- Create feature branches from the `develop` branch.
+- Always "Squash and merge" from feature branches to `develop` to reduce the history size.
+- Always "Merge commit" from `develop` to `main` to retain merge history.
+
+## GitHub Actions Workflow
+
+- Use reusable tasks to eliminate duplication.
+- Create one pull request test action, and register that task as a [branch rule](#github-project-settings) check.
+
 ## 3rd Party Tools
 
 - [AwesomeAssertions](https://awesomeassertions.org/)