From 214a2aad552fa1e64c7aadbe9763650a1bcd55e0 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 14 Oct 2024 17:54:43 -0600 Subject: [PATCH 01/11] Bump dotnet-coverage from 17.12.5 to 17.12.6 (#297) Bumps [dotnet-coverage](https://github.com/microsoft/codecoverage) from 17.12.5 to 17.12.6. - [Commits](https://github.com/microsoft/codecoverage/commits) --- updated-dependencies: - dependency-name: dotnet-coverage dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .config/dotnet-tools.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index b57f73a5..b668e6db 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -9,7 +9,7 @@ ] }, "dotnet-coverage": { - "version": "17.12.5", + "version": "17.12.6", "commands": [ "dotnet-coverage" ] From 698b73d825ae56dceb8fdbb56ce0579d505db7b3 Mon Sep 17 00:00:00 2001 From: Andrew Arnott Date: Fri, 18 Oct 2024 16:13:54 -0600 Subject: [PATCH 02/11] Do NOT fail a pipeline build due to nuget vulnerabilities They should remain as warnings. --- .github/workflows/build.yml | 2 +- azure-pipelines/dotnet.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 68662895..00b3dd3f 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -43,7 +43,7 @@ jobs: run: azure-pipelines/variables/_pipelines.ps1 shell: pwsh - name: ๐Ÿ›  build - run: dotnet build -t:build,pack --no-restore -c ${{ env.BUILDCONFIGURATION }} -warnaserror /bl:"${{ runner.temp }}/_artifacts/build_logs/build.binlog" + run: dotnet build -t:build,pack --no-restore -c ${{ env.BUILDCONFIGURATION }} -warnAsError -warnNotAsError:NU1901,NU1902,NU1903,NU1904 /bl:"${{ runner.temp }}/_artifacts/build_logs/build.binlog" - name: ๐Ÿงช test run: azure-pipelines/dotnet-test-cloud.ps1 -Configuration ${{ env.BUILDCONFIGURATION }} -Agent ${{ runner.os }} shell: pwsh diff --git a/azure-pipelines/dotnet.yml b/azure-pipelines/dotnet.yml index 51241549..b422cfc9 100644 --- a/azure-pipelines/dotnet.yml +++ b/azure-pipelines/dotnet.yml @@ -3,7 +3,7 @@ parameters: steps: -- script: dotnet build -t:build,pack --no-restore -c $(BuildConfiguration) -warnaserror /bl:"$(Build.ArtifactStagingDirectory)/build_logs/build.binlog" +- script: dotnet build -t:build,pack --no-restore -c $(BuildConfiguration) -warnAsError -warnNotAsError:NU1901,NU1902,NU1903,NU1904 /bl:"$(Build.ArtifactStagingDirectory)/build_logs/build.binlog" displayName: ๐Ÿ›  dotnet build - powershell: azure-pipelines/dotnet-test-cloud.ps1 -Configuration $(BuildConfiguration) -Agent $(Agent.JobName) -PublishResults From 93a31bb6e94358ae6ca110e5a892b6470db018a1 Mon Sep 17 00:00:00 2001 From: Andrew Arnott Date: Fri, 18 Oct 2024 16:46:58 -0600 Subject: [PATCH 03/11] Avoid running tests on mono for test project The mono runtime is obsolete for most applications. --- test/Library.Tests/Library.Tests.csproj | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/test/Library.Tests/Library.Tests.csproj b/test/Library.Tests/Library.Tests.csproj index 3a6cc044..134f0669 100644 --- a/test/Library.Tests/Library.Tests.csproj +++ b/test/Library.Tests/Library.Tests.csproj @@ -1,7 +1,8 @@ - net6.0;net472 + net6.0 + $(TargetFrameworks);net472 From dee802a953c0df2d794d826aa9388f48fe673fe3 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 21 Oct 2024 09:13:43 -0600 Subject: [PATCH 04/11] Bump nbgv from 3.6.143 to 3.6.146 (#300) Bumps [nbgv](https://github.com/dotnet/Nerdbank.GitVersioning) from 3.6.143 to 3.6.146. - [Release notes](https://github.com/dotnet/Nerdbank.GitVersioning/releases) - [Commits](https://github.com/dotnet/Nerdbank.GitVersioning/commits) --- updated-dependencies: - dependency-name: nbgv dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .config/dotnet-tools.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index b668e6db..2ccf4bef 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -15,7 +15,7 @@ ] }, "nbgv": { - "version": "3.6.143", + "version": "3.6.146", "commands": [ "nbgv" ] From 026011d97c44d91b5ecf7f57bdd4bd5e86cb3a3e Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 21 Oct 2024 09:13:53 -0600 Subject: [PATCH 05/11] Bump Nerdbank.GitVersioning from 3.6.143 to 3.6.146 (#299) Bumps [Nerdbank.GitVersioning](https://github.com/dotnet/Nerdbank.GitVersioning) from 3.6.143 to 3.6.146. - [Release notes](https://github.com/dotnet/Nerdbank.GitVersioning/releases) - [Commits](https://github.com/dotnet/Nerdbank.GitVersioning/commits) --- updated-dependencies: - dependency-name: Nerdbank.GitVersioning dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- Directory.Packages.props | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Directory.Packages.props b/Directory.Packages.props index adb03b1d..4baf6ece 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -13,7 +13,7 @@ - + From 5dc5cdf385e281221900be34e157eef94797709e Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 29 Oct 2024 14:20:49 +0000 Subject: [PATCH 06/11] Bump powershell from 7.4.5 to 7.4.6 (#301) --- .config/dotnet-tools.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index 2ccf4bef..e60546c0 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -3,7 +3,7 @@ "isRoot": true, "tools": { "powershell": { - "version": "7.4.5", + "version": "7.4.6", "commands": [ "pwsh" ] From 975d9f18afbd791f166d2a6a4a69d8c845bd039e Mon Sep 17 00:00:00 2001 From: Andrew Arnott Date: Tue, 29 Oct 2024 20:10:18 -0600 Subject: [PATCH 07/11] Add github workflow to keep current with Library.Template --- .github/workflows/libtemplate-update.yml | 72 ++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 .github/workflows/libtemplate-update.yml diff --git a/.github/workflows/libtemplate-update.yml b/.github/workflows/libtemplate-update.yml new file mode 100644 index 00000000..564d4af2 --- /dev/null +++ b/.github/workflows/libtemplate-update.yml @@ -0,0 +1,72 @@ +name: Library.Template update + +# PREREQUISITE: This workflow requires the repo to be configured to allow workflows to push commits and create pull requests. +# Visit https://github.com/USER/REPO/settings/actions +# Under "Workflow permissions", select "Read and write permissions" and check "Allow GitHub Actions to create ...pull requests" +# Click Save. + +on: + schedule: + - cron: "0 3 * * Mon" # Sun @ 8 or 9 PM Mountain Time (depending on DST) + workflow_dispatch: + +jobs: + merge: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 # avoid shallow clone so nbgv can do its work. + + - name: merge + shell: pwsh + run: | + $LibTemplateBranch = & ./azure-pipelines/Get-LibTemplateBasis.ps1 -ErrorIfNotRelated + if ($LASTEXITCODE -ne 0) { + exit $LASTEXITCODE + } + + git fetch https://github.com/aarnott/Library.Template $LibTemplateBranch + if ($LASTEXITCODE -ne 0) { + exit $LASTEXITCODE + } + $LibTemplateCommit = git rev-parse FETCH_HEAD + + if ((git rev-list FETCH_HEAD ^HEAD --count) -eq 0) { + Write-Host "There are no Library.Template updates to merge." + exit 0 + } + + git -c http.extraheader="AUTHORIZATION: bearer $env:GH_TOKEN" push origin -u FETCH_HEAD:refs/heads/auto/libtemplateUpdate + - name: pull request + shell: pwsh + run: | + # If there is already an active pull request, don't create a new one. + $existingPR = gh pr list -H auto/libtemplateUpdate --json url | ConvertFrom-Json + if ($existingPR) { + Write-Host "::warning::Skipping pull request creation because one already exists at $($existingPR[0].url)" + exit 0 + } + + $prTitle = "Merge latest Library.Template" + $prBody = "This merges the latest features and fixes from [Library.Template's branch](https://github.com/AArnott/Library.Template/tree/). + +
+ Merge conflicts? + Resolve merge conflicts locally by carrying out these steps: + + ``` + git fetch + git checkout auto/libtemplateUpdate + git merge origin/main + # resolve conflicts + git commit + git push + ``` +
+ + โš ๏ธ Do **not** squash this pull request when completing it. You must *merge* it." + + gh pr create -H auto/libtemplateUpdate -b $prBody -t $prTitle + env: + GH_TOKEN: ${{ github.token }} From 762e59b1da12fe95ffd7130420957d6bcd2c4794 Mon Sep 17 00:00:00 2001 From: Andrew Arnott Date: Sat, 2 Nov 2024 15:10:42 -0600 Subject: [PATCH 08/11] Verify formatted code on GitHub workflows --- .github/workflows/build.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 00b3dd3f..50cf99c8 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -47,6 +47,10 @@ jobs: - name: ๐Ÿงช test run: azure-pipelines/dotnet-test-cloud.ps1 -Configuration ${{ env.BUILDCONFIGURATION }} -Agent ${{ runner.os }} shell: pwsh + - name: ๐Ÿ’…๐Ÿป Verify formatted code + run: dotnet format --verify-no-changes --no-restore + shell: pwsh + if: runner.os == 'Linux' - name: โš™ Update pipeline variables based on build outputs run: azure-pipelines/variables/_pipelines.ps1 shell: pwsh From d046e43768e1553461a261a72ccfa5a26d46e76d Mon Sep 17 00:00:00 2001 From: Andrew Arnott Date: Tue, 5 Nov 2024 08:26:15 -0700 Subject: [PATCH 09/11] Add docfx site placeholder --- .config/dotnet-tools.json | 16 +++++++++--- .github/workflows/docs.yml | 41 ++++++++++++++++++++++++++++++ CONTRIBUTING.md | 9 +++++++ Expand-Template.ps1 | 6 +++++ docfx/.gitignore | 2 ++ docfx/docfx.json | 48 +++++++++++++++++++++++++++++++++++ docfx/docs/features.md | 3 +++ docfx/docs/getting-started.md | 12 +++++++++ docfx/docs/toc.yml | 5 ++++ docfx/index.md | 9 +++++++ docfx/toc.yml | 4 +++ 11 files changed, 152 insertions(+), 3 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 docfx/.gitignore create mode 100644 docfx/docfx.json create mode 100644 docfx/docs/features.md create mode 100644 docfx/docs/getting-started.md create mode 100644 docfx/docs/toc.yml create mode 100644 docfx/index.md create mode 100644 docfx/toc.yml diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index e60546c0..a333e70b 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -6,19 +6,29 @@ "version": "7.4.6", "commands": [ "pwsh" - ] + ], + "rollForward": false }, "dotnet-coverage": { "version": "17.12.6", "commands": [ "dotnet-coverage" - ] + ], + "rollForward": false }, "nbgv": { "version": "3.6.146", "commands": [ "nbgv" - ] + ], + "rollForward": false + }, + "docfx": { + "version": "2.77.0", + "commands": [ + "docfx" + ], + "rollForward": false } } } \ No newline at end of file diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..6e6e64a0 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,41 @@ +name: ๐Ÿ“š Docs + +on: + push: + branches: + - main + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + actions: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: pages + cancel-in-progress: false + +jobs: + publish-docs: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: โš™ Install prerequisites + run: ./init.ps1 -UpgradePrerequisites + + - run: dotnet docfx docfx/docfx.json + name: ๐Ÿ“š Generate documentation + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: docfx/_site + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e56631dd..7ec56f4d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -40,3 +40,12 @@ This repository can be built on Windows, Linux, and OSX. Building, testing, and packing this repository can be done by using the standard dotnet CLI commands (e.g. `dotnet build`, `dotnet test`, `dotnet pack`, etc.). [pwsh]: https://docs.microsoft.com/powershell/scripting/install/installing-powershell?view=powershell-6 + +## Tutorial and API documentation + +API and hand-written docs are found under the `docfx/` directory. and are built by [docfx](https://dotnet.github.io/docfx/). + +You can make changes and host the site locally to preview them by switching to that directory and running the `dotnet docfx --serve` command. +After making a change, you can rebuild the docs site while the localhost server is running by running `dotnet docfx` again from a separate terminal. + +The `.github/workflows/docs.yml` GitHub Actions workflow publishes the content of these docs to github.io if the workflow itself and [GitHub Pages is enabled for your repository](https://docs.github.com/en/pages/quickstart). diff --git a/Expand-Template.ps1 b/Expand-Template.ps1 index e9a567c1..44ef6826 100755 --- a/Expand-Template.ps1 +++ b/Expand-Template.ps1 @@ -166,6 +166,12 @@ try { "(?m)^.*\[GitHub Actions status\].*`r?`n"="" "(?m)^.*\[codecov\].*`r?`n"="" } + Replace-Placeholders -Path "docfx/docfx.json" -Replacements @{ + 'Library'=$LibraryName + } + Replace-Placeholders -Path "docfx/docs/getting-started.md" -Replacements @{ + 'Library'=$LibraryName + } # Specially handle azure-pipelines .yml edits Replace-Placeholders -Path "azure-pipelines/build.yml" -Replacements @{ diff --git a/docfx/.gitignore b/docfx/.gitignore new file mode 100644 index 00000000..d5bcab17 --- /dev/null +++ b/docfx/.gitignore @@ -0,0 +1,2 @@ +_site/ +api/ diff --git a/docfx/docfx.json b/docfx/docfx.json new file mode 100644 index 00000000..729d6731 --- /dev/null +++ b/docfx/docfx.json @@ -0,0 +1,48 @@ +{ + "metadata": [ + { + "src": [ + { + "src": "../src/Library", + "files": [ + "**/*.csproj" + ] + } + ], + "dest": "api" + } + ], + "build": { + "content": [ + { + "files": [ + "**/*.{md,yml}" + ], + "exclude": [ + "_site/**" + ] + } + ], + "resource": [ + { + "files": [ + "images/**" + ] + } + ], + "xref": [ + "https://learn.microsoft.com/en-us/dotnet/.xrefmap.json" + ], + "output": "_site", + "template": [ + "default", + "modern" + ], + "globalMetadata": { + "_appName": "Library", + "_appTitle": "Library", + "_enableSearch": true, + "pdf": false + } + } +} diff --git a/docfx/docs/features.md b/docfx/docs/features.md new file mode 100644 index 00000000..eb3fbeb0 --- /dev/null +++ b/docfx/docs/features.md @@ -0,0 +1,3 @@ +# Features + +TODO diff --git a/docfx/docs/getting-started.md b/docfx/docs/getting-started.md new file mode 100644 index 00000000..eff2c2fb --- /dev/null +++ b/docfx/docs/getting-started.md @@ -0,0 +1,12 @@ +# Getting Started + +## Installation + +Consume this library via its NuGet Package. +Click on the badge to find its latest version and the instructions for consuming it that best apply to your project. + +[![NuGet package](https://img.shields.io/nuget/v/Library.svg)](https://nuget.org/packages/Library) + +## Usage + +TODO diff --git a/docfx/docs/toc.yml b/docfx/docs/toc.yml new file mode 100644 index 00000000..36a38020 --- /dev/null +++ b/docfx/docs/toc.yml @@ -0,0 +1,5 @@ +- name: Features + href: features.md +- name: Getting Started + href: getting-started.md + diff --git a/docfx/index.md b/docfx/index.md new file mode 100644 index 00000000..fc1b9e28 --- /dev/null +++ b/docfx/index.md @@ -0,0 +1,9 @@ +--- +_layout: landing +--- + +# Overview + +This is your docfx landing page. + +Click "Docs" across the top to get get started. diff --git a/docfx/toc.yml b/docfx/toc.yml new file mode 100644 index 00000000..abd17b8c --- /dev/null +++ b/docfx/toc.yml @@ -0,0 +1,4 @@ +- name: Docs + href: docs/ +- name: API + href: api/ From 9b5b71c64552f5cf37cfee9cf96138829b2a6769 Mon Sep 17 00:00:00 2001 From: Andrew Arnott Date: Tue, 5 Nov 2024 10:10:16 -0700 Subject: [PATCH 10/11] Fix release notes link to work by default It also makes it work in the case where `PackageProjectUrl` isn't the github.com repository itself. --- Directory.Build.props | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Directory.Build.props b/Directory.Build.props index 803396d0..98b987f6 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -51,7 +51,7 @@ - $(PackageProjectUrl)/releases/tag/v$(Version) + $(RepositoryUrl)/releases/tag/v$(Version) From 373a8ad2d2da268a7879dc937a2377a7b0b50786 Mon Sep 17 00:00:00 2001 From: Andrew Arnott Date: Tue, 5 Nov 2024 21:00:24 -0700 Subject: [PATCH 11/11] Fix flags sent to codecov.io It only wants one flag, but we were sending two. --- .github/workflows/build.yml | 2 +- azure-pipelines/dotnet.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 50cf99c8..24bc7d9e 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -112,7 +112,7 @@ jobs: path: ${{ runner.temp }}/_artifacts/deployables if: always() - name: ๐Ÿ“ข Publish code coverage results to codecov.io - run: ./azure-pipelines/publish-CodeCov.ps1 -CodeCovToken "${{ env.codecov_token }}" -PathToCodeCoverage "${{ runner.temp }}/_artifacts/coverageResults" -Name "${{ runner.os }} Coverage Results" -Flags "${{ runner.os }}Host,${{ env.BUILDCONFIGURATION }}" + run: ./azure-pipelines/publish-CodeCov.ps1 -CodeCovToken "${{ env.codecov_token }}" -PathToCodeCoverage "${{ runner.temp }}/_artifacts/coverageResults" -Name "${{ runner.os }} Coverage Results" -Flags "${{ runner.os }}" shell: pwsh timeout-minutes: 3 continue-on-error: true diff --git a/azure-pipelines/dotnet.yml b/azure-pipelines/dotnet.yml index b422cfc9..2444928f 100644 --- a/azure-pipelines/dotnet.yml +++ b/azure-pipelines/dotnet.yml @@ -24,7 +24,7 @@ steps: - powershell: | $ArtifactStagingFolder = & "azure-pipelines/Get-ArtifactsStagingDirectory.ps1" $CoverageResultsFolder = Join-Path $ArtifactStagingFolder "coverageResults-$(Agent.JobName)" - azure-pipelines/publish-CodeCov.ps1 -CodeCovToken "$(codecov_token)" -PathToCodeCoverage "$CoverageResultsFolder" -Name "$(Agent.JobName) Coverage Results" -Flags "$(Agent.JobName)Host,$(BuildConfiguration)" + azure-pipelines/publish-CodeCov.ps1 -CodeCovToken "$(codecov_token)" -PathToCodeCoverage "$CoverageResultsFolder" -Name "$(Agent.JobName) Coverage Results" -Flags "$(Agent.JobName)" displayName: ๐Ÿ“ข Publish code coverage results to codecov.io timeoutInMinutes: 3 continueOnError: true