This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community. For more information see the .NET Foundation Code of Conduct.
This project is actively developed using the following software. It is highly recommended that anyone contributing to this library use the same software.
- Visual Studio 2019
- Node.js v16 (v18 breaks our build)
Some projects in the Visual Studio solution require optional or 3rd party components to open. They are not required to build the full solution from the command line using MSBuild, but installing this software will facilitate an enhanced developer experience in Visual Studio.
All other dependencies are acquired via NuGet or NPM.
To build this repository from the command line, you must first execute our init.ps1 script, which downloads NuGet.exe and uses it to restore packages. Assuming your working directory is the root directory of this git repo, and you are running Windows PowerShell, the command is:
.\init.ps1
Most of the repo may be built via building the solution file from Visual Studio 2019, but for a complete build, build from the VS2019 Developer Command Prompt:
.\build.ps1
This repo is structured such that it builds the NuGet package first, using MSBuild. It then builds an NPM package that includes some of the outputs of MSBuild, along with some javascript, for our NPM consumers who want a reasonable versioning story for their NPM packages too.
The Visual Studio 2019 Test Explorer will list and execute all tests.
Use nbgv tag to create a tag for a particular commit that you mean to release.
Learn more about nbgv and its tag and prepare-release commands.
Push the tag.
When your repo is hosted by GitHub and you are using GitHub Actions, you should create a GitHub Release using the standard GitHub UI.
Having previously used nbgv tag and pushing the tag will help you identify the precise commit and name to use for this release.
After publishing the release, the .github\workflows\release.yml workflow will be automatically triggered, which will:
- Find the most recent
.github\workflows\build.ymlGitHub workflow run of the tagged release. - Upload the
deployablesartifact from that workflow run to your GitHub Release. - If you have
NUGET_API_KEYdefined as a secret variable for your repo or org, any nuget packages in thedeployablesartifact will be pushed to nuget.org.
When your repo builds with Azure Pipelines, use the azure-pipelines/release.yml pipeline.
Trigger the pipeline by adding the auto-release tag on a run of your main azure-pipelines.yml pipeline.
API and hand-written docs are found under the docfx/ directory. and are built by 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.
Pull requests are welcome! They may contain additional test cases (e.g. to demonstrate a failure), and/or product changes (with bug fixes or features). All product changes should be accompanied by additional tests to cover and justify the product change unless the product change is strictly an efficiency improvement and no outwardly observable change is expected.
In the master branch, all tests should always pass. Added tests that fail should be marked as Skip
via [Fact(Skip = "Test does not pass yet")] or similar message to keep our test pass rate at 100%.
This repo uses Renovate to keep dependencies current.
Configuration is in the .github/renovate.json file.
Learn more about configuring Renovate.
When changing the renovate.json file, follow these validation steps.
If Renovate is not creating pull requests when you expect it to, check that the Renovate GitHub App is configured for your account or repo.