ptr727.ProjectTemplate.Library 1.0.52

ProjectTemplate

C# .NET project template.

Build and Distribution

• Source Code: GitHub - Source code, issues, discussions, and CI/CD pipelines.
• Versioned Releases: GitHub Releases - Version tagged source code and build artifacts.
• Docker Images: Docker Hub - Container images with all tools pre-installed.
• NuGet Packages: NuGet Packages - .NET libraries published to NuGet.org.
• PyPI Packages: PyPI Packages - Python library published to PyPI.org.

Build Status

Releases

Release Notes

Version: 1.0:

Summary:

• Something.
• And something else.

⚠️ Breaking Changes:

• Something.
• And something else.

See Release History for complete release notes and older versions.

Getting Started

Get started with ProjectTemplate in three easy steps:

⚠️ Important: Some important warning.

ℹ️ Note: Some interesting note.

1. Install ProjectTemplate:

   • Do something.

2. Configure ProjectTemplate:

   • Then something else.

3. Run ProjectTemplate:

   Console --loglevel=Debug
   

See Installation for detailed setup instructions.

Table of Contents

• Build and Distribution
  • Build Status
  • Releases
  • Release Notes
• Getting Started
• Table of Contents
• Use Cases
• Installation
• Configuration
• Usage
  • Command Quick Reference
  • Global Options
  • Test Command
• Questions or Issues
• Development Environment Setup
• 3rd Party Tools
• License
• Template Project Setup
  • Template - TODO List
  • Template - Developer Environment Setup
  • Template - GitHub Setup
  • Template - Branching Workflow

Use Cases

ℹ️ TL;DR: This widget is special because it does something special.

• It does something special.
• And it does something else special.

Installation

Choose an installation method based on your platform and requirements:

• Method 1 (Recommended): Easiest and most up-to-date option.
  • ✅ Some good reason.
  • ⚠️ Some not so good reason.
  • ❌ Strong reason to avoid.
  • Best for: Linux, NAS devices, servers, cross-platform deployments.
• Method 2: Custom configuration options.
  • ✅ Some good reason.
  • ⚠️ Some not so good reason.
  • ❌ Strong reason to avoid.
  • Best for: Specialized devices.

Configuration

⚠️ Important: The spinner setting must be configured before first use.

Required configuration:

• Set foo to something.
• Set bar to something else.

Optional configuration:

• Set advanced to special.
• Some other custom option.

Usage

Console [global options] <command> [command options]

Command Quick Reference

Use the --help option to get a list of all commands and global options.
To get help for a specific command run Console <command> --help.

Global Options

Global options apply to all commands:

General help:

>.\Console\bin\Debug\net10.0\Console --help
Description:
  C# .NET console project

Usage:
  Console [command] [options]

Options:
  -l, --loglevel <Debug|Error|Fatal|Information|Verbose|Warning>  Set the log level (default: Information). [default: Information]
  -f, --logfile <logfile>                                         Write logs to the specified file (optional).
  -c, --logfile-clear                                             Clear the log file before writing (default: false).
  -?, -h, --help                                                  Show help and usage information
  --version                                                       Show version information

Commands:
  test  Test command

Test Command

Test command options:

Test command help:

>.\Console\bin\Debug\net10.0\Console test --help
Description:
  Test command

Usage:
  Console test [options]

Options:
  -t, --test <test>                                               Test command option (optional).
  -?, -h, --help                                                  Show help and usage information
  -l, --loglevel <Debug|Error|Fatal|Information|Verbose|Warning>  Set the log level (default: Information). [default: Information]
  -f, --logfile <logfile>                                         Write logs to the specified file (optional).
  -c, --logfile-clear                                             Clear the log file before writing (default: false).

Questions or Issues

For General Questions:

• Use the Discussions forum for general questions.

For Bug Reports:

• Ask in the Discussions forum if you are not sure if it is a bug.
• Check the existing Issues tracker for known problems.
• If the issue is unique and a bug, file it in Issues, and include all pertinent steps to reproduce the issue.

Development Environment Setup

The recommended setup is one of the per-language Dev Containers under .devcontainer/:

• .devcontainer/dotnet/ — .NET 10 SDK + GitHub CLI. Pair with DotNet.code-workspace.
• .devcontainer/python/ — Python 3.14 + uv + GitHub CLI. Pair with Python.code-workspace.

Each container bind-mounts your SSH public key, allowed-signers file, and gh config from the host so commits sign correctly. gh is pre-authenticated when the host token is file-backed; macOS Keychain and Linux libsecret-backed tokens require an in-container gh auth login — see the credential-store nuance section.

Windows note: Python work is intentionally not supported on the Windows host. The Python extension caches the Linux-layout PyPiLibrary/.venv/bin/python against a venv whose actual Windows path is PyPiLibrary\.venv\Scripts\python.exe, breaking Ruff. Use the python devcontainer.

Recommended (devcontainer):

1. Complete host setup once per machine (git identity, SSH key, allowed_signers, gh auth login, SSH commit signing).
2. Clone the repo, open the matching workspace (DotNet.code-workspace or Python.code-workspace) in VS Code with the Dev Containers extension, and run Reopen in Container — pick the language flavor.
3. The postCreateCommand runs dotnet tool restore (.NET container) or installs uv and runs uv sync (Python container). No git hooks are installed by default — see "Optional: enable git hooks locally" below.

Alternative (host install):

• Install Developer Tools:

  • Install .NET SDK:

    # Windows
    winget install Microsoft.DotNet.SDK.10
    
    # Linux
    apt install dotnet-sdk-10.0
    

  • Install Visual Studio Code:

    # Windows
    winget install Microsoft.VisualStudioCode
    

  • Install Visual Studio:

    # Windows
    winget install Microsoft.VisualStudio.Community
    

• Clone and Configure Project:

  • Clone the repository and initialize tools:

    # Clone from CLI (or clone from VSCode)
    git clone -b main https://github.com/ptr727/[Project].git ./[Project]
    
    # Initialize dotnet tools
    cd ./[Project]
    dotnet tool restore
    

  • Open DotNet.code-workspace (or Python.code-workspace) in Visual Studio Code.

  • Open [Project].slnx in Visual Studio.

Optional: enable git hooks locally:

Hooks are not shipped with the template — CI is the lint backstop. Opt in per language if you want pre-commit checks locally.

• For .NET work — install Husky.Net:

  dotnet new tool-manifest  # if no tool manifest exists yet
  dotnet tool install Husky
  dotnet husky install
  dotnet husky add pre-commit -c "dotnet csharpier check . && dotnet format style --verify-no-changes --severity=info"
  

• For Python work — install pre-commit:

  uv tool install pre-commit
  pre-commit install
  

  Sample .pre-commit-config.yaml (the hooks shell into PyPiLibrary/ because the uv project — and therefore ruff/pyright and their configs — lives there, not at the repo root):

  repos:
    - repo: local
      hooks:
        - id: ruff-check
          name: ruff check
          entry: uv run --directory PyPiLibrary ruff check
          language: system
          files: ^PyPiLibrary/.*\.py$
          pass_filenames: false
        - id: ruff-format
          name: ruff format
          entry: uv run --directory PyPiLibrary ruff format --check
          language: system
          files: ^PyPiLibrary/.*\.py$
          pass_filenames: false
        - id: pyright
          name: pyright
          entry: uv run --directory PyPiLibrary pyright
          language: system
          files: ^PyPiLibrary/.*\.py$
          pass_filenames: false
  

CI runs these same checks on every PR, so hooks are purely a local convenience.

3rd Party Tools

3rd Party tools used in this project:

• API Ninjas
• AwesomeAssertions
• Bring Your Own Badge
• Create Pull Request
• CSharpier
• GH Release
• Git Auto Commit
• GitHub Actions
• GitHub Dependabot
• Nerdbank.GitVersioning
• Serilog
• xUnit.Net

License

Licensed under the MIT License

Template Project Setup

Template - TODO List

• Configure git for SSH signing and SSH forwarding in dev containers — see docs/host-setup.md, docs/ssh-signing.md, and docs/devcontainer.md.
• Decide whether your project needs the .NET (NuGetLibrary/) side, the Python (PyPiLibrary/) side, or both. Delete the unused folder and remove its references from ProjectTemplate.slnx, .github/dependabot.yml, and the corresponding .github/workflows/build-*-task.yml.
• Start on Linux to avoid file permission issues when moving from Windows.
• Configure the Developer Environment.
• Open the project directory (not the workspace) in Visual Studio Code, and rename (Ctrl-Shift-H) all instances of ProjectTemplate to [NewProject] in code.
• Rename DotNet.code-workspace to [NewProject].code-workspace and Python.code-workspace to [NewProject]-Python.code-workspace, or delete the workspace for the language you don't need. Rename ProjectTemplate.slnx to [NewProject].slnx.
• Open the workspace file for the language you kept ([NewProject].code-workspace and/or [NewProject]-Python.code-workspace) in Visual Studio Code.
• Delete any projects and associated actions that will not be used, update dependencies in actions to remove deleted actions.
• Rename projects to match the naming, update .slnx and .csproj files, and update actions to match the naming.
• Update the namespace in .cs and .csproj files to match the naming.
• Update all ref-links in README.md to point to the naming.
• Publish to GitHub from VSCode to create a new empty GitHub repository.
• Commit and push the first-branch.
• Edit and iterate only in first-branch until ready to start with git history.
• Setup main as the first permanent branch when ready.
• Configure GitHub for the new repository.
• Follow the Branching Workflow.
• Delete the Project Template Setup section from README.md.

Template - Developer Environment Setup

Template - Git Setup

• ⚠️ Prerequisites:

  • Configure git for SSH signing — see SSH commit signing.
  • Configure host prerequisites (SSH key, allowed_signers, gh auth) — see host setup.
  • Configure SSH forwarding for dev containers — see devcontainer setup.

• Setup new project from template:

  # Clone the template project
  git clone -b main https://github.com/ptr727/ProjectTemplate.git ./[NewProject]
  
  # Reset git to start a new repo
  rm -r ./[NewProject]/.git
  cd ./[NewProject]
  git init -b first-branch
  
  # Init dotnet tools
  dotnet tool restore
  
  # Update dotnet tools
  dotnet tool update --all
  dotnet outdated --upgrade:prompt
  

• Setup new project from scratch:

  ⚠️ Linux: Start configuration on Linux to avoid file permission issues.

  # Init git
  mkdir ./[NewProject]
  cd ./[NewProject]
  git init -b first-branch
  
  # Init dotnet tools
  dotnet new tool-manifest
  dotnet tool install csharpier
  dotnet tool install dotnet-outdated-tool
  

• Use first-branch for all the initial project setup and testing.

• When ready, only when ready, create main branch from first-branch with no history:

  # Create main branch with no history
  git checkout --orphan main
  git commit --allow-empty -m "temp"
  
  # Squash merge changes
  git merge --squash first-branch
  git commit -m "Initial import (squashed)"
  
  # Drop the temporary commit
  git reset --hard HEAD~1
  
  # Delete first-branch
  git branch -D first-branch
  

Template - GitHub Setup

GitHub secrets setup:

• Create a NuGet API Key.

  • Save the Key as NUGET_API_KEY in:
    • GitHub project security Settings / Secrets / Actions.
    • GitHub project security Settings / Secrets / Dependabot.
    • GitHub Local Actions Settings / Secrets.

• Create a Docker Hub Personal Access Token.

  • 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.

• Create a GitHub App for the codegen and merge-bot workflows.

  • App name: ptr727-codegen. Bot user: ptr727-codegen[bot].
  • Permissions required (repository scope):
    • Contents: Read & write — push commits to the codegen branch and merge bot PRs.
    • Pull requests: Read & write — open, update, and merge pull requests.
    • Metadata: Read-only (auto-required).
  • Note the App ID from the app's settings page; generate a private key (downloads a .pem file).
  • Install the app on your account and grant it access to the repository. The app must be both created and installed — creating it alone is not sufficient (actions/create-github-app-token fails with Not Found if the app isn't installed on the repository).
  • Save the App ID as CODEGEN_APP_ID and the private key contents as CODEGEN_APP_PRIVATE_KEY in both of:
    • GitHub project security Settings / Secrets / Actions — for the codegen workflow and the codegen merge job.
    • GitHub project security Settings / Secrets / Dependabot — required because Dependabot-triggered pull_request workflow runs use a separate, restricted secret context that doesn't see Actions secrets. Without the App secrets in the Dependabot store, the merge-dependabot job in merge-bot-pull-request.yml can't mint an App token and the PR will never auto-merge.
  • If the codegen workflows require additional secrets (e.g. third-party API keys), register them in the Actions store; if a Dependabot-triggered workflow ever needs them, register them in the Dependabot store too.
  • The App token is used by both the codegen workflow (run-codegen-pull-request-task.yml) and every job in merge-bot-pull-request.yml. App-authored pushes/PRs trigger downstream pull_request and push workflow events directly — unlike GITHUB_TOKEN-authored events, which are blocked by GitHub's recursion guard. This is why publish-release.yml fires on the merge commit after Dependabot or codegen auto-merge, and why the codegen workflow no longer needs the legacy close/reopen dance to trigger auto-merge.
  • The codegen auto-merge condition in merge-bot-pull-request.yml (merge-codegen job) requires:
    • github.event.pull_request.user.login == 'ptr727-codegen[bot]' — PR was opened by the App.
    • github.actor == 'ptr727-codegen[bot]' — the event was triggered by the App. This stops the job from re-invoking gh pr merge --auto on a maintainer-triggered synchronize, but does not disable auto-merge once it was already enabled by the initial bot-driven opened event. If a maintainer pushes commits to a codegen PR with auto-merge already on, the next CI pass will merge them. To edit a codegen PR safely, disable auto-merge first via gh pr merge --disable-auto <PR> (or the GitHub UI button) before pushing.
    • github.event.pull_request.head.repo.full_name == github.repository — PR is from this repo (not a fork).
    • Strict head/base pairing — (head.ref == 'codegen-main' && base.ref == 'main') || (head.ref == 'codegen-develop' && base.ref == 'develop'). Codegen runs as a matrix opening one PR per branch; this pairing prevents a misconfigured workflow from sneaking a codegen-develop branch into main or vice versa.

  Codegen targets main AND develop in parallel (matrix in run-codegen-pull-request-task.yml), so generated content lands on both branches independently without any back-merging. See AGENTS.md "Branching Model" for why this dual-target pattern beats develop-only-with-flow-through.

Codegen workflow schedule:

• run-periodic-codegen-pull-request.yml runs every Monday at 02:00 UTC, plus on-demand via workflow_dispatch. It uses the App token (CODEGEN_APP_ID + CODEGEN_APP_PRIVATE_KEY) to commit, open the PR as ptr727-codegen[bot], and let the merge-bot auto-merge once CI passes. No PAT, no close/reopen dance.

GitHub project settings:

• General:
  • Default branch: main
  • Pull requests — both merge methods enabled at the repo level so each branch ruleset can pick the right one (develop = Squash, main = Merge):
    • Allow merge commits ✓ (required for develop → main releases)
    • Allow squash merging ✓ (required for feature → develop merges)
    • Allow rebase merging — disabled (no flow uses it; the develop ruleset forbids it anyway)
    • Always suggest updating pull request branches
    • Allow auto-merge
• Rules / Rulesets — separate rulesets per branch so allowed merge methods differ (develop = squash-only; main = merge-commit-only, per AGENTS.md). Everything else is shared.
  • "Develop":
    • Target branches: develop.
    • Allowed merge methods: Squash
    • Require linear history (develop is kept linear; main carries merge commits by design, so this setting belongs to develop only)
    • Plus shared settings (below).
  • "Main":
    • Target branches: main.
    • Allowed merge methods: Merge
    • Plus shared settings (below).
  • Shared settings (apply to both rulesets):
    • Restrict deletions
    • Require signed commits
    • Require a pull request before merging
      • Dismiss stale pull request approvals when new commits are pushed
      • Require conversation resolution before merging
    • Require status checks to pass
      • Require branches to be up to date before merging
      • Status checks that are required: Check pull request workflow status
    • Block force pushes
    • Automatically request Copilot code review
      • Review new pushes
      • Review draft pull requests
• Actions / General:
  • Allow GitHub Actions to create and approve pull requests

Template - Branching Workflow

See AGENTS.md "Branching Model" for the authoritative definition. Summary:

• Persistent main and develop branches, each with its own ruleset (above). Both must always be building error free.
• Feature branches off develop. Only commit on feature branches, never directly to develop or main.
• Feature → develop: squash-merge (develop ruleset enforces this; develop is kept linear).
• develop → main: merge-commit (preserves develop's commit list as a real second-parent reference on main; main ruleset enforces this).
• develop is forward-only. No main → develop back-merges. The develop squash-only ruleset physically blocks merge commits.
• Bots open parallel PRs against both branches. .github/dependabot.yml duplicates each ecosystem entry per branch, and .github/workflows/run-codegen-pull-request-task.yml runs as a matrix (branch names codegen-main and codegen-develop). Each branch absorbs its own bot PRs independently — neither falls behind, no back-merges needed.

Template - Release Distribution Model: Push vs. Pull

This template ships with a push-on-merge release model — every commit on main triggers .github/workflows/publish-release.yml which publishes a GitHub release, NuGet/PyPI uploads, Docker tags, and platform executables. With the dual-target bot model (Dependabot/codegen targeting both branches), this means every Dependabot bump that lands on main produces a new release. That's the right default for projects whose consumers pull at their own cadence (Docker pulls, NuGet/PyPI installs, manual binary downloads) — releases are cheap and frequent, consumers update on their own schedule.

For projects whose consumers are pushed updates (HACS for Home Assistant, package managers that auto-update integrations, Linux distros that vendor from main), every release is a forced update to all users. Frequent bot-driven releases become noise. To switch to a manual main-release model while keeping the rest of the dual-target dual-channel flow:

1. Edit .github/workflows/publish-release.yml and change the trigger:

    on:
   -  push:
   -    branches: [ main, develop ]
   -  workflow_dispatch:
   +  push:
   +    branches: [ develop ]
   +  workflow_dispatch:
   

   Result: develop pushes still publish dev releases automatically (PEP 440 .dev0 to PyPI, NBGV-prerelease tags on NuGet, prerelease GitHub releases). main pushes no longer auto-publish; you trigger the release manually via the GitHub Actions UI (workflow_dispatch) when a real release is wanted.

2. (Optional) narrow what flows into main automatically. If a sea of Dependabot PRs on main is noisy without auto-release, either:

   • Drop the main-target Dependabot entries from .github/dependabot.yml (so deps update on develop only, and reach main through the next develop → main release the maintainer triggers — closer to a pure develop-only flow with manual cadence), or
   • Keep dual-target Dependabot and let the merge-bot auto-merge them silently into main; main always has fresh code, but ships only when the maintainer dispatches a release.

For an example of the manual-release model in production, see homeassistant-purpleair — that integration ships through HACS (push distribution) and uses workflow_dispatch for actual releases.