Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
100 lines (67 loc) · 5.39 KB

CONTRIBUTING.md

File metadata and controls

100 lines (67 loc) · 5.39 KB

Microsoft.VisualStudio.SlowCheetah

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Pull requests

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repositories using our CLA.

Prerequisites

All dependencies can be installed by running the init.ps1 script at the root of the repository using Windows PowerShell or PowerShell Core (on any OS). Some dependencies installed by init.ps1 may only be discoverable from the same command line environment the init script was run from due to environment variables, so be sure to launch Visual Studio or build the repo from that same environment. Alternatively, run init.ps1 -InstallLocality Machine (which may require elevation) in order to install dependencies at machine-wide locations so Visual Studio and builds work everywhere.

The only prerequisite for building, testing, and deploying from this repository is the .NET SDK. You should install the version specified in global.json or a later version within the same major.minor.Bxx "hundreds" band. For example if 2.2.300 is specified, you may install 2.2.300, 2.2.301, or 2.2.310 while the 2.2.400 version would not be considered compatible by .NET SDK. See .NET Core Versioning for more information.

Package restore

The easiest way to restore packages may be to run init.ps1 which automatically authenticates to the feeds that packages for this repo come from, if any. dotnet restore or nuget restore also work but may require extra steps to authenticate to any applicable feeds.

Building

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

Releases

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.

GitHub Actions

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:

  1. Find the most recent .github/workflows/build.yml GitHub workflow run of the tagged release.
  2. Upload the deployables artifact from that workflow run to your GitHub Release.
  3. If you have NUGET_API_KEY defined as a secret variable for your repo or org, any nuget packages in the deployables artifact will be pushed to nuget.org.

Azure Pipelines

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.

Tutorial and API documentation

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.

Updating dependencies

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.

Merging latest from Library.Template

Maintaining your repo based on this template

The best way to keep your repo in sync with Library.Template's evolving features and best practices is to periodically merge the template into your repo:

git fetch
git checkout origin/main
./tools/MergeFrom-Template.ps1
# resolve any conflicts, then commit the merge commit.
git push origin -u HEAD