vm2.Functional 1.0.0-preview.2

vm2.Functional

A starter vm2 package scaffold. Customize the code, tests, benchmarks, docs, and workflows as needed.

Getting started

• Build:

  dotnet restore
  dotnet build
  

• Test:

  • from CLI, if it is not built yet (builds on MTP v2):

    dotnet run --project tests/Functional.Tests/Functional.Tests.csproj
    

  • from CLI, if it is already built in CLI or VSCode (MTP v2):

    • any OS or shell:

      dotnet test tests/Functional.Tests/bin/Debug/net10.0/Functional.Tests.dll
      

    • on Windows CLI (already built in CLI or VSCode - on MTP v2):

      tests/Functional.Tests/bin/Debug/net10.0/Functional.Tests.exe
      

    • on Linux or MacOS CLI (already built in CLI or VSCode - on MTP v2):

      tests/Functional.Tests/bin/Debug/net10.0/Functional.Tests
      

  • from Visual Studio:

    • use the Test Explorer to build and run tests (builds on MTP v1)

    • if it is already built in Visual Studio (MTP v1), from the CLI you can run:

      dotnet test
      

• Benchmarks (if included):

  dotnet run --project benchmarks/Functional.Benchmarks/Functional.Benchmarks.csproj --configuration Release
  

  In a personal development environment, you can run benchmarks with defined SHORT_RUN preprocessor directive. The run will be faster, although less accurate, but still suitable for quick iterations.

Package metadata

• Package ID: vm2.Functional
• Version: 0.0.0
• License: MIT
• Repository: https://github.com/vmelamed/vm2.Functional

Repository Layout

vm2.<name>/
├── .github/
│   ├── dependabot.yml *      # dependabot configuration (see note below)
│   ├── CONVENTIONS.md *      # Claude conventions for contributing to the repo
│   ├── copilot-instructions.md
│   ├── PULL_REQUEST_TEMPLATE.md *
│   └── workflows/            # GitHub Actions workflows
│       ├── AutoMerge.yaml *
│       ├── ClearCache.yaml *
│       ├── CI.yaml **
│       ├── Prerelease.yaml **
│       └── Release.yaml **
├── benchmarks/               # Benchmark projects (recommended)
│   └── vm2.<name>.Benchmarks/
│       ├── EchoBenchmarks.cs
│       ├── <name>.Benchmarks.csproj
│       ├── Program.cs
│       └── usings.cs
├── changelog/                # git-cliff toml files for updating the Changelog from commit messages
│   ├── cliff.prerelease.toml *
│   └── cliff.release.toml *
├── docs/                     # Extra documentation - in addition to the README.md in the repo root (optional)
│   └── README.md
├── examples/                 # Example program(s) (one file program(s) or project(s) - optional)
│   └── Program.cs
├── src/                      # Source code
│   └── <name>/
│       ├── <name>.csproj
│       ├── <name>.Api.cs
│       └── usings.cs
├── tests/                    # Test projects (highly recommended)
│   └── <name>.Tests/
│       ├── <name>.Tests.csproj
│       ├── <name>ApiTests.cs
│       └── usings.cs
├── .editorconfig *
├── .gitattributes *
├── .gitmessage *
├── .gitignore *
├── CLAUDE.md
├── codecov.yaml *
├── coverage.settings.xml *
├── Directory.Build.props **
├── Directory.Packages.props **
├── global.json *
├── LICENSE *
├── NuGet.config *
├── README.md
├── testconfig.json *
├── vm2.Functional.slnx
└── CHANGELOG.md

• .github/workflows: CI, prerelease, release, clear-cache.
• src/Functional: the library source code
• tests/Functional.Tests: xUnit + MTP tests, includes testconfig.json
• benchmarks/Functional.Benchmarks: BenchmarkDotNet suite (optional)
• examples/Functional.Example: minimal console sample (optional)
• docs/: documentation starter (optional)
• scripts/: bootstrap helpers
• changelog/: git-cliff configs for prerelease/release changelog updates

Next steps

Create GitHub repository using the generated bootstrap script: $VM2_REPOS/vm2.DevOps/scripts/bash/setup-repo.sh. It will:

• Update README, CHANGELOG, and package metadata.
• Use the repository setup script scripts/setup-repo.sh to initialize the repository as follows:
  • create a local Git repository and make the initial commit
  • set local Git configuration settings:
    • core.hooksPath = $VM2_REPOS/vm2.DevOps/scripts/githooks
    • commit.template = .gitmessage
    • merge.ff = only
    • pull.rebase = true
    • fetch.prune = true
    • push.autoSetupRemote = true
    • rerere.enabled = true
    • rerere.autoUpdate = true
    • rebase.autoStash = true
    • merge.conflictstyle = zdiff3
    • push.useForceIfIncludes = true
    • tag.sort = version:refname
    • merge.nugetlock.name = NuGet lockfile - take the incoming side and regenerate
    • merge.nugetlock.driver = cp -f %B %A && echo "vm2: %P auto-resolved (took the incoming side) - regenerate with: dotnet restore --force-evaluate" >&2
  • create a remote repository on GitHub and link it to the local repository
  • push the initial commit to the remote repository on GitHub
  • set repository settings:
    • Default branch = main
    • Has wiki = false
    • Has issues = true
    • Has projects = false
    • Has pull requests = true
    • Pull request creation policy = all
    • Allow merge commit = false
    • Allow squash merge = false
    • Allow rebase merge = true
    • Allow auto merge = true
    • Delete branch on merge = true
    • Visibility = public
    • Actions permissions:
      • Can approve pull request reviews = true
      • Default workflow permissions = read
  • protect the main branch by enabling required checks and requiring pull requests:
    • Enforcement = active
    • Repository admin bypass = present
    • Deletion = present
    • Required linear history = present
    • Pull request = present
    • Required approving review count = present
    • Dismiss stale reviews on push = present
    • Require code owner review = present
    • Require last push approval = present
    • Required review thread resolution = present
    • Required reviewers = present
    • Allowed merge methods = present
    • Required status checks = present
    • Do not enforce on create = present
    • Strict required status checks policy = present
    • Non fast forward = present
    • Required status checks list:
      • Postrun-CI = present (combines the results from build, test, benchmark, test package)
  • interactively set required variables for workflows:
    • CONFIGURATION = Release
    • DOTNET_VERSION = 10.0.x
    • MAX_GEN1_COLLECTS = 2
    • MAX_GEN2_COLLECTS = 1
    • MAX_REGRESSION_PCT = 20
    • MIN_COVERAGE_PCT = 80
    • MINVERDEFAULTPRERELEASEIDENTIFIERS = preview.0
    • MINVERTAGPREFIX = v
    • NUGET_SERVER = github (can be also nuget)
    • RESET_BENCHMARK_THRESHOLDS = false
    • SAVE_PACKAGE_ARTIFACTS = false
    • VERBOSE = false (use for workflow debugging)
    • ACTIONS_RUNNER_DEBUG = false
    • ACTIONS_STEP_DEBUG = false
  • interactively set required secrets for workflows (prepare the secrets in advance):
    • BENCH_DISPATCH_PAT = [secret]
    • BENCHER_API_TOKEN = [secret]
    • CODECOV_TOKEN = [secret]
    • NUGET_API_KEY = [secret]
    • RELEASE_PAT = [secret]
    • REPORTGENERATOR_LICENSE = [secret]
    • Dependabot Secrets:
      • GH_PACKAGES_TOKEN = [secret]
• Changelog: prerelease workflow appends a prerelease section; release workflow adds a stable header with "See prereleases below." (prerelease sections stay intact).