Merge remote-tracking branch 'docs/main' into code-fence-languages

.github/allowed-actions.js

@@ -13,6 +13,7 @@ module.exports = [
   'actions/stale@af4072615903a8b031f986d25b1ae3bf45ec44d4', //actions/stale@v3.0.13
   'crowdin/github-action@fd9429dd63d6c0f8a8cb4b93ad8076990bd6e688',
   'crykn/copy_folder_to_another_repo_action@abc264e1c16eb3d7b1f7763bfdb0e1699ad43120',
+  'cschleiden/actions-linter@43fd4e08e52ed40c0e2782dc2425694388851576',
   'dawidd6/action-delete-branch@47743101a121ad657031e6704086271ca81b1911',
   'docker://chinthakagodawita/autoupdate-action:v1',
   'fkirc/skip-duplicate-actions@36feb0d8d062137530c2e00bd278d138fe191289',

.github/workflows/autoupdate-branch.yml

@@ -7,7 +7,7 @@ jobs:
   autoupdate:
     if: github.repository == 'github/docs-internal' || github.repository == 'github/docs'
     name: autoupdate
-    runs-on: ubuntu-18.04
+    runs-on: ubuntu-latest
     steps:
       - uses: docker://chinthakagodawita/autoupdate-action:v1
         env:

.github/workflows/codeql.yml

@@ -2,9 +2,11 @@ name: CodeQL analysis
 
 on:
   push:
-    branches: main
+    branches:
+      - main
   pull_request:
-    branches: main
+    branches:
+      - main
     paths:
       - '**/*.js'
       - '.github/workflows/codeql.yml'

.github/workflows/site-policy-sync.yml

@@ -8,6 +8,8 @@ on:
       - main
     types:
       - closed
+    paths:
+      - 'content/github/site-policy/**'
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
@@ -33,8 +35,8 @@ jobs:
         with:
           source_folder: 'content/github/site-policy'
           destination_repo: 'github/site-policy'
-          destination_branch: 'non-substantive-changes'
+          destination_branch: 'repo-sync'
           destination_folder: 'Policies'
           user_email: 'pcihon@users.noreply.github.com'
           user_name: 'pcihon'
-          commit_msg: 'Mirroring non-substantive changes.'
+          commit_msg: 'Automatic sync from GitHub Docs.'

.github/workflows/test-windows.yml

@@ -4,12 +4,14 @@ name: Node.js Tests - Windows
 
 on:
   workflow_dispatch:
+  pull_request:
   schedule:
     - cron: '50 19 * * *' # once a day at 19:50 UTC / 11:50 PST
 
 jobs:
   test:
     runs-on: windows-latest
+    if: (github.event_name != 'pull_request') || (github.event_name == 'pull_request' && (contains(github.event.pull_request.labels.*.name, 'Windows') || contains(github.event.pull_request.labels.*.name, 'windows')))
     strategy:
       fail-fast: false
       matrix:

.github/workflows/triage-unallowed-contributions.yml

@@ -104,6 +104,7 @@ jobs:
               body: reviewMessage,
               event: 'REQUEST_CHANGES'
             })
+            exit 1 # prevents further steps from running and fails workflow
       # When the most recent review was CHANGES_REQUESTED and the existing
       # PR no longer contains unallowed changes, dismiss the previous review
       - name: Dismiss pull request review

.github/workflows/workflow-lint.yml

@@ -0,0 +1,22 @@
+name: Lint workflows
+
+on:
+  workflow_dispatch:
+  # push:
+  #   branches:
+  #     - main
+  # pull_request:
+  #   branches-ignore:
+  #     - translations
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f
+
+      - name: Run linter
+        uses: cschleiden/actions-linter@43fd4e08e52ed40c0e2782dc2425694388851576
+        with:
+          workflows: '[".github/workflows/*.yml"]'

README.md

@@ -18,7 +18,7 @@ We accept a lot of [different contributions](CONTRIBUTING.md/#types-of-contribut
 
 #### Click **make a contribution** from docs
 
-As you're using the GitHub Docs, you may find something in an article that you'd like to add to, update, or change. Click on **make a contribution** to navigate directly to that article in the codebase, so that you can begin making your contribution.
+As you're using GitHub Docs, you may find something in an article that you'd like to add to, update, or change. Click on **make a contribution** to navigate directly to that article in the codebase, so that you can begin making your contribution.
 
 <img src="./assets/images/contribution_cta.png" width="400">
 

content/README.md

@@ -24,6 +24,7 @@ See the [contributing docs](/CONTRIBUTING.md) for general information about work
   - [Escaping single quotes](#escaping-single-quotes)
 - [Autogenerated mini TOCs](#autogenerated-mini-tocs)
 - [Versioning](#versioning)
+  - [Free-pro-team vs. GitHub.com versioning](#free-pro-team-vs.-github.com-versioning)
 - [Filenames](#filenames)
 - [Whitespace control](#whitespace-control)
 - [Links and image paths](#links-and-image-paths)
@@ -213,6 +214,12 @@ A content file can have **two** types of versioning:
 * Liquid statements in content (**optional**)
     * Conditionally render content depending on the current version being viewed. See [contributing/liquid-helpers](../contributing/liquid-helpers.md) for more info. Note Liquid conditionals can also appear in `data` and `include` files.
 
+### Free-pro-team vs. GitHub.com versioning
+
+As of early 2021, the `free-pro-team@latest` version is **only** supported in content files (in both frontmatter and Liquid versioning) and throughout the docs site backend. It is **not** user facing. A helper function called `lib/remove-fpt-from-path.js` removes the version from URLs. Users now select `GitHub.com` in the Article Versions dropdown instead of `Free, Pro, Team`.
+
+The convenience function allows us to continue supporting a consistent versioning structure under-the-hood while not displaying plan information to users that may be potentially confusing.
+
 ## Filenames
 
 When adding a new article, make sure the filename is a [kebab-cased](https://en.wikipedia.org/wiki/Letter_case#Special_case_styles) version of the title you use in the article's [`title`](#title) frontmatter. This can get tricky when a title has punctuation (such as "GitHub's Billing Plans"). A test will flag any discrepancies between title and filename. To override this requirement for a given article, you can add [`allowTitleToDifferFromFilename`](#allowtitletodifferfromfilename) frontmatter.
@@ -224,7 +231,7 @@ When using Liquid conditionals in lists or tables, you can use [whitespace contr
 Just add a hyphen on either the left, right, or both sides to indicate that there should be no newline on that side. For example, this statement removes a newline on the left side:
 
 ```
-{%- if page.version == 'dotcom' %}
+{%- if currentVersion == 'free-pro-team@latest' %}
 ```
 
 These characters are especially important in [index pages](#index-pages) comprised of list items.
@@ -238,9 +245,9 @@ For example, if you include the following link in a content file:
 ```
 /github/writing-on-github/creating-a-saved-reply
 ```
-When viewed on GitHub.com docs, the link gets rendered with the language code and version:
+When viewed on GitHub.com docs, the link gets rendered with the language code:
 ```
-/en/free-pro-team@latest/github/writing-on-github/creating-a-saved-reply
+/en/github/writing-on-github/creating-a-saved-reply
 ```
 and when viewed on GitHub Enterprise Server docs, the version is included as well:
 ```

content/actions/guides/building-and-testing-net.md

@@ -0,0 +1,248 @@
+---
+title: Building and testing .NET
+intro: You can create a continuous integration (CI) workflow to build and test your .NET project.
+product: '{% data reusables.gated-features.actions %}'
+versions:
+  free-pro-team: '*'
+  enterprise-server: '>=2.22'
+---
+
+### Introduction
+
+This guide shows you how to build, test, and publish a .NET package.
+
+{% data variables.product.prodname_dotcom %}-hosted runners have a tools cache with preinstalled software, which includes the .NET Core SDK. For a full list of up-to-date software and the preinstalled versions of .NET Core SDK, see [software installed on {% data variables.product.prodname_dotcom %}-hosted runners](/actions/reference/specifications-for-github-hosted-runners).
+
+### Prerequisites
+
+You should already be familiar with YAML syntax and how it's used with {% data variables.product.prodname_actions %}. For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions)."
+
+We recommend that you have a basic understanding of the .NET Core SDK. For more information, see [Getting started with .NET](https://dotnet.microsoft.com/learn).
+
+### Starting with the .NET workflow template
+
+{% data variables.product.prodname_dotcom %} provides a .NET workflow template that should work for most .NET projects, and this guide includes examples that show you how to customize this template. For more information, see the [.NET workflow template](https://github.com/actions/setup-dotnet).
+
+To get started quickly, add the template to the `.github/workflows` directory of your repository.
+
+{% raw %}
+```yaml
+name: dotnet package
+
+on: [push]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        dotnet-version: [ '2.2.103', '3.0', '3.1.x' ]
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Setup .NET Core SDK ${{ matrix.dotnet }}
+      uses: actions/setup-dotnet@v1.6.0
+      with:
+        dotnet-version: {{ matrix.dotnet-version }}
+    - name: Install dependencies
+      run: dotnet restore
+    - name: Build
+      run: dotnet build --configuration Release --no-restore
+    - name: Test
+      run: dotnet test --no-restore --verbosity normal
+```
+{% endraw %}
+
+### Specifying a .NET version
+
+To use a preinstalled version of the .NET Core SDK on a {% data variables.product.prodname_dotcom %}-hosted runner, use the `setup-dotnet` action. This action finds a specific version of .NET from the tools cache on each runner, and adds the necessary binaries to `PATH`. These changes will persist for the remainder of the job.
+
+The `setup-dotnet` action is the recommended way of using .NET with {% data variables.product.prodname_actions %}, because it ensures consistent behavior across different runners and different versions of .NET. If you are using a self-hosted runner, you must install .NET and add it to `PATH`. For more information, see the [`setup-dotnet`](https://github.com/marketplace/actions/setup-dotnet).
+
+#### Using multiple .NET versions
+
+{% raw %}
+```yaml
+name: dotnet package
+
+on: [push]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        dotnet: [ '2.2.103', '3.0', '3.1.x' ]
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Setup dotnet ${{ matrix.dotnet-version }}
+      uses: actions/setup-dotnet@v1.6.0
+      with:
+        dotnet-version: ${{ matrix.dotnet-version }}
+    # You can test your matrix by printing the current dotnet version
+    - name: Display dotnet version
+      run: dotnet --version
+```
+{% endraw %}
+
+#### Using a specific .NET version
+
+You can configure your job to use a specific version of .NET, such as `3.1.3`. Alternatively, you can use semantic version syntax to get the latest minor release. This example uses the latest minor release of .NET 3.
+
+{% raw %}
+```yaml
+    - name: Setup .NET 3.x
+      uses: actions/setup-dotnet@v2
+      with:
+        # Semantic version range syntax or exact version of a dotnet version
+        dotnet-version: '3.x' 
+```
+{% endraw %}
+
+### Installing dependencies
+
+{% data variables.product.prodname_dotcom %}-hosted runners have the NuGet package manager installed. You can use the dotnet CLI to install dependencies from the NuGet package registry before building and testing your code. For example, the YAML below installs the `Newtonsoft` package.
+
+{% raw %}
+```yaml
+steps:
+- uses: actions/checkout@v2
+- name: Setup dotnet
+  uses: actions/setup-dotnet@v1.6.0
+  with:
+    dotnet-version: '3.1.x'
+- name: Install dependencies
+  run: dotnet add package Newtonsoft.Json --version 12.0.1
+```
+{% endraw %}
+
+{% if currentVersion == "free-pro-team@latest" %}
+
+#### Caching dependencies
+
+You can cache NuGet dependencies using a unique key, which allows you to restore the dependencies for future workflows with the [`cache`](https://github.com/marketplace/actions/cache) action. For example, the YAML below installs the `Newtonsoft` package.
+
+For more information, see "[Caching dependencies to speed up workflows](/actions/guides/caching-dependencies-to-speed-up-workflows)."
+
+{% raw %}
+```yaml
+steps:
+- uses: actions/checkout@v2
+- name: Setup dotnet
+  uses: actions/setup-dotnet@v1.6.0
+  with:
+    dotnet-version: '3.1.x'
+- uses: actions/cache@v2
+  with:
+    path: ~/.nuget/packages
+    # Look to see if there is a cache hit for the corresponding requirements file
+    key: ${{ runner.os }}-nuget-${{ hashFiles('**/packages.lock.json') }}
+    restore-keys: |
+      ${{ runner.os }}-nuget
+- name: Install dependencies
+  run: dotnet add package Newtonsoft.Json --version 12.0.1
+```
+{% endraw %}
+
+{% note %}
+
+**Note:** Depending on the number of dependencies, it may be faster to use the dependency cache. Projects with many large dependencies should see a performance increase as it cuts down the time required for downloading. Projects with fewer dependencies may not see a significant performance increase and may even see a slight decrease due to how NuGet installs cached dependencies. The performance varies from project to project.
+
+{% endnote %}
+
+{% endif %}
+
+### Building and testing your code
+
+You can use the same commands that you use locally to build and test your code. This example demonstrates how to use `dotnet build` and `dotnet test` in a job:
+
+{% raw %}
+```yaml
+steps:
+- uses: actions/checkout@v2
+- name: Setup dotnet
+  uses: actions/setup-dotnet@v1.6.0
+  with:
+    dotnet-version: '3.1.x'
+- name: Install dependencies
+  run: dotnet restore
+- name: Build
+  run: dotnet build
+- name: Test with the dotnet CLI
+  run: dotnet test
+```
+{% endraw %}
+
+### Packaging workflow data as artifacts
+
+After a workflow completes, you can upload the resulting artifacts for analysis. For example, you may need to save log files, core dumps, test results, or screenshots. The following example demonstrates how you can use the `upload-artifact` action to upload test results.
+
+For more information, see "[Persisting workflow data using artifacts](/github/automating-your-workflow-with-github-actions/persisting-workflow-data-using-artifacts)."
+
+{% raw %}
+```yaml
+name: dotnet package
+
+on: [push]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        dotnet-version: [ '2.2.103', '3.0', '3.1.x' ]
+
+      steps:
+      - uses: actions/checkout@v2
+      - name: Setup dotnet
+        uses: actions/setup-dotnet@v1.6.0
+        with:
+          dotnet-version: ${{ matrix.dotnet-version }}
+      - name: Install dependencies
+        run: dotnet restore
+      - name: Test with dotnet
+        run: dotnet test --logger trx --results-directory "TestResults-${{ matrix.dotnet-version }}"
+      - name: Upload dotnet test results
+        uses: actions/upload-artifact@v2
+        with:
+          name: dotnet-results-${{ matrix.dotnet-version }}
+          path: TestResults-${{ matrix.dotnet-version }}
+        # Use always() to always run this step to publish test results when there are test failures
+        if: ${{ always() }}
+```
+{% endraw %}
+
+### Publishing to package registries
+
+You can configure your workflow to publish your Dotnet package to a package registry when your CI tests pass. You can use repository secrets to store any tokens or credentials needed to publish your binary. The following example creates and publishes a package to {% data variables.product.prodname_registry %} using `dotnet core cli`.
+
+{% raw %}
+```yaml
+name: Upload dotnet package
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-dotnet@v1
+    with:
+        dotnet-version: '3.1.x' # SDK Version to use.
+        source-url: https://nuget.pkg.github.com/<owner>/index.json
+    env:
+        NUGET_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}
+    - run: dotnet build <my project>
+    - name: Create the package
+    run: dotnet pack --configuration Release <my project>
+    - name: Publish the package to GPR
+    run: dotnet nuget push <my project>/bin/Release/*.nupkg
+```
+{% endraw %}