diff --git a/ProjectTemplate.code-workspace b/ProjectTemplate.code-workspace index 51273e3b..757ea750 100644 --- a/ProjectTemplate.code-workspace +++ b/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", ] } diff --git a/README.md b/README.md index 8e7d4a2f..1d4f3b31 100644 --- a/README.md +++ b/README.md @@ -20,17 +20,13 @@ 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" @@ -38,25 +34,37 @@ Packages published on [NuGet](https://www.nuget.org/packages/ptr727.ProjectTempl 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/)