From 783c7c6979656a0be00248a8ee8e4d6cfce15a6b Mon Sep 17 00:00:00 2001 From: Jess Hosman <1183847+jhosman@users.noreply.github.com> Date: Thu, 2 Nov 2023 11:38:25 -0600 Subject: [PATCH] Deal with all occurrences of `docs.github.com` (#44293) --- .../supplemental-arguments-and-settings.md | 4 + ...grating-from-circleci-to-github-actions.md | 6 +- .../configuring-dependency-review.md | 14 +- .../about-contributing-to-github-docs.md | 6 +- .../label-reference.md | 4 +- .../working-on-github-docs-in-a-codespace.md | 2 +- .../about-the-content-model.md | 4 +- .../quickstart-content-type.md | 2 +- .../style-guide.md | 2 +- .../tutorial-content-type.md | 2 +- .../configuring-redirects.md | 6 +- .../writing-for-github-docs/templates.md | 200 ++++++++++-------- ...ing-your-custom-domain-for-github-pages.md | 2 +- .../github-corporate-terms-of-service.md | 1 + .../github-marketplace-developer-agreement.md | 1 + .../github-terms/github-terms-of-service.md | 1 + .../github-privacy-statement.md | 1 + .../github-sirt-description-rfc-2350.md | 7 +- ...plicable-to-us-federal-government-users.md | 1 + .../github-ae-data-protection-agreement.md | 1 + .../github-ae-product-specific-terms.md | 1 + ...b-enterprise-cloud-evaluation-agreement.md | 1 + 22 files changed, 159 insertions(+), 110 deletions(-) diff --git a/content/actions/migrating-to-github-actions/automated-migrations/supplemental-arguments-and-settings.md b/content/actions/migrating-to-github-actions/automated-migrations/supplemental-arguments-and-settings.md index 7f51bae83fab..88c0b92f58f8 100644 --- a/content/actions/migrating-to-github-actions/automated-migrations/supplemental-arguments-and-settings.md +++ b/content/actions/migrating-to-github-actions/automated-migrations/supplemental-arguments-and-settings.md @@ -108,6 +108,8 @@ gh actions-importer list-features You should see an output similar to the following. + + ```shell Available feature flags: @@ -131,6 +133,8 @@ Enable features by passing --enable-features feature-1 feature-2 Disable features by passing --disable-features feature-1 feature-2 ``` + + To toggle feature flags, you can use either of the following methods: - Use the `--enable-features` and `--disable-features` options when running a `gh actions-importer` command. - Use an environment variable for each feature flag. diff --git a/content/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-circleci-to-github-actions.md b/content/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-circleci-to-github-actions.md index 10b359be2dc7..c0c1b05815d3 100644 --- a/content/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-circleci-to-github-actions.md +++ b/content/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-circleci-to-github-actions.md @@ -18,7 +18,7 @@ topics: - CD shortTitle: Migrate from CircleCI --- - + {% data reusables.actions.enterprise-github-hosted-runners %} ## Introduction @@ -227,6 +227,8 @@ workflows: ### GitHub Actions syntax for using databases and service containers + + ```yaml name: Containers @@ -272,6 +274,8 @@ jobs: run: bundle exec rake ``` + + For more information, see "[AUTOTITLE](/actions/using-containerized-services/about-service-containers)." ## Complete Example diff --git a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-dependency-review.md b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-dependency-review.md index 5497140817e4..56e9af296776 100644 --- a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-dependency-review.md +++ b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-dependency-review.md @@ -116,6 +116,8 @@ Notice that all of the examples use a short version number for the action (`v3`) This {% data variables.dependency-review.action_name %} example file illustrates how you can use the available configuration options. + + ```yaml copy name: 'Dependency Review' on: [pull_request] @@ -133,7 +135,7 @@ Notice that all of the examples use a short version number for the action (`v3`) - name: Dependency Review uses: actions/dependency-review-action@v3 with: - # Possible values: "critical", "high", "moderate", "low" + # Possible values: "critical", "high", "moderate", "low" fail-on-severity: critical {% ifversion dependency-review-action-licenses %} @@ -155,6 +157,8 @@ Notice that all of the examples use a short version number for the action (`v3`) {% endif %} ``` + + ### Using a configuration file to set up {% data variables.dependency-review.action_name %} 1. Add a new YAML workflow to your `.github/workflows` folder and use `config-file` to specify that you are using a configuration file. @@ -180,12 +184,12 @@ Notice that all of the examples use a short version number for the action (`v3`) with: # ([String]). Representing a path to a configuration file local to the repository or in an external repository. # Possible values: An absolute path to a local file or an external file. - config-file: './.github/dependency-review-config.yml' + config-file: './.github/dependency-review-config.yml' # Syntax for an external file: OWNER/REPOSITORY/FILENAME@BRANCH config-file: 'github/octorepo/dependency-review-config.yml@main' # ([Token]) Use if your configuration file resides in a private external repository. - # Possible values: Any GitHub token with read access to the private external repository. + # Possible values: Any GitHub token with read access to the private external repository. external-repo-token: 'ghp_123456789abcde' ``` @@ -193,6 +197,8 @@ Notice that all of the examples use a short version number for the action (`v3`) This YAML example file illustrates how you can use the available configuration options. + + ```yaml copy # Possible values: "critical", "high", "moderate", "low" fail-on-severity: critical @@ -224,5 +230,7 @@ Notice that all of the examples use a short version number for the action (`v3`) {% endif %} ``` + + For further details about the configuration options, see [`dependency-review-action`](https://github.com/actions/dependency-review-action#readme). {% endif %} diff --git a/content/contributing/collaborating-on-github-docs/about-contributing-to-github-docs.md b/content/contributing/collaborating-on-github-docs/about-contributing-to-github-docs.md index be317c8483e4..4e322cbe6019 100644 --- a/content/contributing/collaborating-on-github-docs/about-contributing-to-github-docs.md +++ b/content/contributing/collaborating-on-github-docs/about-contributing-to-github-docs.md @@ -9,7 +9,7 @@ versions: {% data variables.product.prodname_dotcom %} documentation is open source. Anyone can contribute to the docs in the public `docs` repository: https://github.com/github/docs. {% data variables.product.prodname_dotcom %} employees work on the documentation in a copy of this repository called `docs-internal`. The two repositories are automatically synced to keep them both up to date with changes merged into the `main` branch of either repository. For simplicity, we'll refer to "the documentation repository" in the articles about contributing to {% data variables.product.prodname_docs %}. -The documentation repository is the place to discuss and collaborate on the documentation that is published here on [docs.github.com](/). +The documentation repository is the place to discuss and collaborate on the documentation that is published here on [docs.github.com](/). {% ifversion discussions %} @@ -31,7 +31,7 @@ If you'd like help troubleshooting a documentation issue or pull request you're [Issues](/github/managing-your-work-on-github/about-issues) are used to track tasks that contributors can help with. If an issue has a `triage` label, we haven't reviewed it yet, and you shouldn't begin work on it. -If you've found something in the documentation content, or something about the docs.github.com website, that should be updated, search the open issues to see if someone else has reported the same thing. If it's something new, open an issue using a [template](https://github.com/github/docs/issues/new/choose). We'll use the issue to have a conversation about the problem you'd like to be fixed. +If you've found something in the documentation content, or something about the docs.github.com website, that should be updated, search the open issues to see if someone else has reported the same thing. If it's something new, open an issue using a [template](https://github.com/github/docs/issues/new/choose). We'll use the issue to have a conversation about the problem you'd like to be fixed. {% note %} @@ -75,6 +75,6 @@ We do not currently accept pull requests for translated content. ## Site policy -{% data variables.product.prodname_dotcom %}'s site policies are also published on docs.github.com. +{% data variables.product.prodname_dotcom %}'s site policies are also published on docs.github.com. If you find a typo in the site policy section, you can open a pull request to fix it. For anything else, see "[Contributing](https://github.com/github/site-policy/blob/main/CONTRIBUTING.md)" in the `site-policy` repository. diff --git a/content/contributing/collaborating-on-github-docs/label-reference.md b/content/contributing/collaborating-on-github-docs/label-reference.md index 77ec90da768c..cea50bcd249f 100644 --- a/content/contributing/collaborating-on-github-docs/label-reference.md +++ b/content/contributing/collaborating-on-github-docs/label-reference.md @@ -12,6 +12,6 @@ You can use labels to locate a particular type of issue. For example, click the | --- | --- | | [`help wanted`](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) | Problems or updates that anyone in the community can start working on. | | [`good first issue`](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) | Problems or updates we think are ideal for beginners. | -| [`content`](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3Acontent) | Problems or updates in the content on docs.github.com. These will usually require some knowledge of Markdown. | -| [`engineering`](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3Aengineering) | Problems or updates involving the functionality of the docs.github.com website. Fixing these issues will usually require some knowledge of JavaScript/Node.js or YAML. | +| [`content`](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3Acontent) | Problems or updates in the content on docs.github.com. These will usually require some knowledge of Markdown. | +| [`engineering`](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3Aengineering) | Problems or updates involving the functionality of the docs.github.com website. Fixing these issues will usually require some knowledge of JavaScript/Node.js or YAML. | | [`codespaces`](https://github.com/github/docs/labels/codespaces)
[`desktop`](https://github.com/github/docs/labels/desktop)
[`graphql`](https://github.com/github/docs/labels/graphql) | Labels for filtering issues by a product or documentation area. | diff --git a/content/contributing/setting-up-your-environment-to-work-on-github-docs/working-on-github-docs-in-a-codespace.md b/content/contributing/setting-up-your-environment-to-work-on-github-docs/working-on-github-docs-in-a-codespace.md index 94733c9d9785..ff9b7e66c202 100644 --- a/content/contributing/setting-up-your-environment-to-work-on-github-docs/working-on-github-docs-in-a-codespace.md +++ b/content/contributing/setting-up-your-environment-to-work-on-github-docs/working-on-github-docs-in-a-codespace.md @@ -25,7 +25,7 @@ The following steps assume you have {% data variables.product.prodname_github_co The "Setting up your codespace" page is displayed. After a short time the browser-based version of {% data variables.product.prodname_vscode %} is displayed. 1. Use the Explorer to navigate to the markdown file you want to edit. If the file is an article, it will be located in the `content` directory. If the file is reusable content, it will be located in the `data` directory. - In most cases, the path to an article in the `content` directory matches the path in the URL, minus the `.md` file extension. For example, the source for the article `https://docs.github.com/en/codespaces/getting-started/quickstart` is the markdown file `content/codespaces/getting-started/quickstart.md`. + In most cases, the path to an article in the `content` directory matches the path in the URL, minus the `.md` file extension. For example, the source for the article `https://docs.github.com/en/codespaces/getting-started/quickstart` is the markdown file `content/codespaces/getting-started/quickstart.md`. 1. Edit the markdown file as required. 1. Save your changes. 1. Commit and push your changes, either using the Source Control view, or using Git commands from the Terminal. For more information, see "[AUTOTITLE](/get-started/using-git/about-git)." diff --git a/content/contributing/style-guide-and-content-model/about-the-content-model.md b/content/contributing/style-guide-and-content-model/about-the-content-model.md index cbe215f15e1f..9f15c0d57f02 100644 --- a/content/contributing/style-guide-and-content-model/about-the-content-model.md +++ b/content/contributing/style-guide-and-content-model/about-the-content-model.md @@ -26,7 +26,7 @@ Docs are organized into multiple levels of hierarchy on our site. ## Homepage content -The {% data variables.product.prodname_docs %} homepage, [docs.github.com](/), highlights the most important topics that people want to find. We limit the number of doc sets on the homepage so that people can find information and the homepage does not become overcrowded and difficult to search. +The {% data variables.product.prodname_docs %} homepage, [docs.github.com](/), highlights the most important topics that people want to find. We limit the number of doc sets on the homepage so that people can find information and the homepage does not become overcrowded and difficult to search. The homepage includes all top-level doc sets and some categories. Content on the homepage is organized around {% data variables.product.prodname_dotcom %} concepts and practices. For example, the "CI/CD and DevOps" group includes top-level doc sets for {% data variables.product.prodname_actions %}, {% data variables.product.prodname_registry %}, and {% data variables.product.prodname_pages %}. @@ -71,7 +71,7 @@ Categories are organized around a feature or a discrete set of tasks within a to - Examples - [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github) - [AUTOTITLE](/pull-requests/committing-changes-to-your-project) - + ### Intros for categories All categories have intros. Intros should be one sentence long and general or high-level enough to scale with future product changes. If you significantly change a category’s structure, check its intro for needed updates. diff --git a/content/contributing/style-guide-and-content-model/quickstart-content-type.md b/content/contributing/style-guide-and-content-model/quickstart-content-type.md index d58acf4eee24..0aefab08dcf8 100644 --- a/content/contributing/style-guide-and-content-model/quickstart-content-type.md +++ b/content/contributing/style-guide-and-content-model/quickstart-content-type.md @@ -33,7 +33,7 @@ Contents of quickstarts: - If relevant troubleshooting content exists for the quickstart, provide links to it. - Next steps - Provide a quick recap of what has been accomplished in the quickstart as a means of transitioning to next steps. - - Include 2-3 actionable next steps that someone can take after completing the quickstart. Always link to conceptual content on the feature or product. You can also link off to other related information on docs.github.com or in {% data variables.product.prodname_learning %}. + - Include 2-3 actionable next steps that someone can take after completing the quickstart. Always link to conceptual content on the feature or product. You can also link off to other related information on docs.github.com or in {% data variables.product.prodname_learning %}. ## Title guidelines for quickstarts diff --git a/content/contributing/style-guide-and-content-model/style-guide.md b/content/contributing/style-guide-and-content-model/style-guide.md index 69af57911c84..b6c6b7077cf4 100644 --- a/content/contributing/style-guide-and-content-model/style-guide.md +++ b/content/contributing/style-guide-and-content-model/style-guide.md @@ -10,7 +10,7 @@ redirect_from: {% note %} -**Note:** These guidelines are specific to {% data variables.product.company_short %}'s documentation. For general style questions or guidance on topics not covered here, see the [Microsoft Style Guide](https://docs.microsoft.com/style-guide/welcome/). For markup specific to source content on docs.github.com, see "[AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs)." For any questions about the GitHub brand, see our "[GitHub Brand Guide](https://brand.github.com)." +**Note:** These guidelines are specific to {% data variables.product.company_short %}'s documentation. For general style questions or guidance on topics not covered here, see the [Microsoft Style Guide](https://docs.microsoft.com/style-guide/welcome/). For markup specific to source content on docs.github.com, see "[AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs)." For any questions about the GitHub brand, see our "[GitHub Brand Guide](https://brand.github.com)." {% endnote %} diff --git a/content/contributing/style-guide-and-content-model/tutorial-content-type.md b/content/contributing/style-guide-and-content-model/tutorial-content-type.md index 7bfcca8857b2..59b27ac90e01 100644 --- a/content/contributing/style-guide-and-content-model/tutorial-content-type.md +++ b/content/contributing/style-guide-and-content-model/tutorial-content-type.md @@ -38,7 +38,7 @@ Contents of tutorials: - Next steps - Include 2-3 actionable next steps that someone can take after completing the tutorial. Link off to other related information like: - Projects on {% data variables.product.prodname_dotcom %} that illustrate the introduced concepts - - Relevant information on docs.github.com + - Relevant information on docs.github.com - Relevant {% data variables.product.prodname_learning %} - Relevant published talks, blog posts, or Community Forum series posts by Hubbers diff --git a/content/contributing/writing-for-github-docs/configuring-redirects.md b/content/contributing/writing-for-github-docs/configuring-redirects.md index b348f9f50ef5..3e1f4890cf63 100644 --- a/content/contributing/writing-for-github-docs/configuring-redirects.md +++ b/content/contributing/writing-for-github-docs/configuring-redirects.md @@ -34,7 +34,7 @@ See [`redirect_from`](https://github.com/github/docs/blob/main/content/README.md ### Automatic redirects for URLs that do not include a version -If a URL for a page is entered without a version (`https://docs.github.com/ARTICLE` instead of `https://docs.github.com/VERSION/ARTICLE`), the site will automatically redirect it to the first available version of the page. +If a URL for a page is entered without a version (`https://docs.github.com/ARTICLE` instead of `https://docs.github.com/VERSION/ARTICLE`), the site will automatically redirect it to the first available version of the page. The order of precedence is specified in [`lib/all-versions.js`](https://github.com/github/docs/blob/main/src/versions/lib/all-versions.js). The current order of precedence is: @@ -43,9 +43,9 @@ The order of precedence is specified in [`lib/all-versions.js`](https://github.c 1. {% data variables.product.prodname_ghe_server %} (`ghes`) 1. {% data variables.product.prodname_ghe_managed %} (`ghae`) -If a page titled `ARTICLE` is only available in {% data variables.product.prodname_ghe_cloud %} and {% data variables.product.prodname_ghe_server %}, the link `https://docs.github.com/ARTICLE` will automatically redirect to `https://docs.github.com/enterprise-cloud@latest/ARTICLE` because {% data variables.product.prodname_ghe_cloud %} has precedence over {% data variables.product.prodname_ghe_server %}. +If a page titled `ARTICLE` is only available in {% data variables.product.prodname_ghe_cloud %} and {% data variables.product.prodname_ghe_server %}, the link `https://docs.github.com/ARTICLE` will automatically redirect to `https://docs.github.com/enterprise-cloud@latest/ARTICLE` because {% data variables.product.prodname_ghe_cloud %} has precedence over {% data variables.product.prodname_ghe_server %}. -If `ARTICLE` is available in Free, Pro, or Team, no redirect will occur because `fpt` pages do not have a version segment, so the `fpt` content at `https://docs.github.com/ARTICLE` will render. +If `ARTICLE` is available in Free, Pro, or Team, no redirect will occur because `fpt` pages do not have a version segment, so the `fpt` content at `https://docs.github.com/ARTICLE` will render. ### Redirects across versions diff --git a/content/contributing/writing-for-github-docs/templates.md b/content/contributing/writing-for-github-docs/templates.md index b00b797ae8c7..6fd75bd76cdd 100644 --- a/content/contributing/writing-for-github-docs/templates.md +++ b/content/contributing/writing-for-github-docs/templates.md @@ -10,6 +10,8 @@ versions: Use the content model for full instructions and examples on how to write conceptual content. For more information, see "[AUTOTITLE](/contributing/style-guide-and-content-model/conceptual-content-type)." + + ```yaml {% raw %}--- title: 'About ' @@ -23,7 +25,7 @@ versions: - version --- -{% comment %} +{% comment %} - Follow the guidelines in https://docs.github.com/contributing/writing-for-github-docs/content-model#conceptual to write this article. - Great intros give readers a quick understanding of what's in the article, so they can tell whether it's relevant to them before moving ahead. For more tips, see https://docs.github.com/contributing/writing-for-github-docs/content-model - For product callout info, see https://github.com/github/docs/tree/main/content#product @@ -33,31 +35,35 @@ versions: ## A section here -{% comment %} -Write one or two paragraphs about the main idea of your topic, as a summary. -Make sure you don't have any content that isn't preceded by a header, or it won't be linkable in our table of contents. +{% comment %} +Write one or two paragraphs about the main idea of your topic, as a summary. +Make sure you don't have any content that isn't preceded by a header, or it won't be linkable in our table of contents. {% endcomment %} ## Another section here -{% comment %} -Write one or two paragraphs about another element of your topic. -Keep adding headers and sections until you've completed your article. +{% comment %} +Write one or two paragraphs about another element of your topic. +Keep adding headers and sections until you've completed your article. {% endcomment %} ## Further reading -{% comment %} -Optionally, include a bulleted list of related articles the user can reference to extend the concepts covered in this article. Consider linking to procedural articles or tutorials that help the user use the information in your article. +{% comment %} +Optionally, include a bulleted list of related articles the user can reference to extend the concepts covered in this article. Consider linking to procedural articles or tutorials that help the user use the information in your article. {% endcomment %} - "[Article title](article-URL)"{% endraw %} ``` + + ## Referential article template Use the content model for full instructions and examples on how to write referential content. For more information, see "[AUTOTITLE](/contributing/style-guide-and-content-model/referential-content-type)." + + ```yaml {% raw %}--- title: Nouns describing your subject @@ -65,47 +71,51 @@ shortTitle: # Max 31 characters intro: 'Article intro. See tips for a great intro below.' product: "{{ optional product callout }}" type: reference -topics: +topics: - # One or more from list of allowed topics: https://github.com/github/docs/blob/main/data/allowed-topics.js versions: - --- -{% comment %} +{% comment %} Follow the guidelines in https://docs.github.com/contributing/writing-for-github-docs/content-model#referential to write this article.-- > -Great intros give readers a quick understanding of what's in the article, so they can tell whether it's relevant to them before moving ahead. For more tips, see https://docs.github.com/contributing/writing-for-github-docs/content-model -For product callout info, see https://github.com/github/docs/tree/main/content#product -For product version instructions, see https://github.com/github/docs/tree/main/content#versioning -Remove these comments from your article file when you're done writing +Great intros give readers a quick understanding of what's in the article, so they can tell whether it's relevant to them before moving ahead. For more tips, see https://docs.github.com/contributing/writing-for-github-docs/content-model +For product callout info, see https://github.com/github/docs/tree/main/content#product +For product version instructions, see https://github.com/github/docs/tree/main/content#versioning +Remove these comments from your article file when you're done writing {% endcomment %} ## A section here -{% comment %} -Write one or two paragraphs about the main idea of your topic, as a summary. -Make sure you don't have any content that isn't preceded by a header, or it won't be linkable in our table of contents. +{% comment %} +Write one or two paragraphs about the main idea of your topic, as a summary. +Make sure you don't have any content that isn't preceded by a header, or it won't be linkable in our table of contents. {% endcomment %} ## Another section here -{% comment %} -Write one or two paragraphs about another element of your topic. -Keep adding headers and sections until you've completed your article. +{% comment %} +Write one or two paragraphs about another element of your topic. +Keep adding headers and sections until you've completed your article. {% endcomment %} ## Further reading -{% comment %} -Optionally, include a bulleted list of related articles the user can reference to extend the concepts covered in this article. Consider linking to procedural articles or tutorials that help the user use the information in your article. +{% comment %} +Optionally, include a bulleted list of related articles the user can reference to extend the concepts covered in this article. Consider linking to procedural articles or tutorials that help the user use the information in your article. {% endcomment %} - "[Article title](article-URL)"{% endraw %} ``` + + ## Procedural article template Use the content model for full instructions and examples on how to write procedural content. For more information, see "[AUTOTITLE](/contributing/style-guide-and-content-model/procedural-content-type)." + + ```yaml {% raw %}--- title: Start with a present participle @@ -113,69 +123,73 @@ shortTitle: # Max 31 characters intro: 'Article intro. See tips for a great intro below.' product: "{{ optional product callout }}" type: how_to -topics: +topics: - # One or more from list of allowed topics: https://github.com/github/docs/blob/main/data/allowed-topics.js versions: - --- -{% comment %} +{% comment %} Follow the guidelines in https://docs.github.com/contributing/writing-for-github-docs/content-model#procedural to write this article.-- > -Great intros give readers a quick understanding of what's in the article, so they can tell whether it's relevant to them before moving ahead. For more tips, see https://docs.github.com/contributing/writing-for-github-docs/content-model -For product callout info, see https://github.com/github/docs/tree/main/content#product -For product version instructions, see https://github.com/github/docs/tree/main/content#versioning -Remove these comments from your article file when you're done writing +Great intros give readers a quick understanding of what's in the article, so they can tell whether it's relevant to them before moving ahead. For more tips, see https://docs.github.com/contributing/writing-for-github-docs/content-model +For product callout info, see https://github.com/github/docs/tree/main/content#product +For product version instructions, see https://github.com/github/docs/tree/main/content#versioning +Remove these comments from your article file when you're done writing {% endcomment %} ## Procedural section header here -{% comment %} -Include prerequisite information or specific permissions information here. -Then write procedural steps following the instructions in https://docs.github.com/contributing/style-guide-and-content-model/style-guide#procedural-steps. -Check if there's already a reusable string for the step you want to write in https://github.com/github/docs/tree/main/data/reusables. Look at the source file for a procedure located in the same area of the user interface to find reusables. +{% comment %} +Include prerequisite information or specific permissions information here. +Then write procedural steps following the instructions in https://docs.github.com/contributing/style-guide-and-content-model/style-guide#procedural-steps. +Check if there's already a reusable string for the step you want to write in https://github.com/github/docs/tree/main/data/reusables. Look at the source file for a procedure located in the same area of the user interface to find reusables. {% endcomment %} -## Optionally, another procedural section here +## Optionally, another procedural section here -{% comment %} -Keep adding procedures until you've finished writing your article. +{% comment %} +Keep adding procedures until you've finished writing your article. {% endcomment %} ## Further reading -{% comment %} -Optionally, include a bulleted list of related articles the user can reference to extend the concepts covered in this article. Consider linking to procedural articles or tutorials that help the user use the information in your article. +{% comment %} +Optionally, include a bulleted list of related articles the user can reference to extend the concepts covered in this article. Consider linking to procedural articles or tutorials that help the user use the information in your article. {% endcomment %} - "[Article title](article-URL)"{% endraw %} ``` + + ## Quickstart article template Use the content model for full instructions and examples on how to write quickstarts. For more information, see "[AUTOTITLE](/contributing/style-guide-and-content-model/quickstart-content-type)." + + ```yaml {% raw %}--- title: Quickstart title shortTitle: # Max 31 characters intro: 'Article intro. Highlight that the guide is quick and to the point.' type: quick_start -topics: +topics: - # One or more from list of allowed topics: https://github.com/github/docs/blob/main/data/allowed-topics.js versions: - --- -{% comment %} +{% comment %} Follow the guidelines in https://docs.github.com/contributing/writing-for-github-docs/content-model#quickstart to write this article. For product version instructions, see https://github.com/github/docs/tree/main/content#versions. The entire quickstart should be about 600 words long or take about five minutes to read. -Remove these comments from your article file when you're done writing +Remove these comments from your article file when you're done writing {% endcomment %} ## Introduction -{% comment %} +{% comment %} Build on the quick phrasing above by - Clarifying the audience - Clearly stating prerequisites and prior knowledge needed @@ -184,40 +198,44 @@ Build on the quick phrasing above by ## Step one: Action the user will take -{% comment %} -In one sentence, describe what the user will do in this step -Steps should break down the tasks the user will complete in sequential order -Avoid replicating conceptual information that is covered elsewhere, provide inline links instead. Only include conceptual information unique to this use case. +{% comment %} +In one sentence, describe what the user will do in this step +Steps should break down the tasks the user will complete in sequential order +Avoid replicating conceptual information that is covered elsewhere, provide inline links instead. Only include conceptual information unique to this use case. {% endcomment %} ### Task chunk -{% comment %} -A step may require the user to perform several tasks - break those tasks down into chunks, allowing the user to scan quickly to find their place if they navigated away from this screen to perform the task. -An example might be creating a {% endraw %}{% data variables.product.pat_generic %}{% raw %} for the action to use and then storing it in secrets -For UI based tasks, include the button or options the users should click -If the task adds code, include the code in context (don't just show `needs setup` show the entire `setup` and `dependent` jobs) +{% comment %} +A step may require the user to perform several tasks - break those tasks down into chunks, allowing the user to scan quickly to find their place if they navigated away from this screen to perform the task. +An example might be creating a {% endraw %}{% data variables.product.pat_generic %}{% raw %} for the action to use and then storing it in secrets +For UI based tasks, include the button or options the users should click +If the task adds code, include the code in context (don't just show `needs setup` show the entire `setup` and `dependent` jobs) {% endcomment %} ### Another task chunk ## Step 2: Do the next thing -{% comment %} -Rinse and repeat, adding steps and tasks until the tutorial is complete +{% comment %} +Rinse and repeat, adding steps and tasks until the tutorial is complete {% endcomment %} ## Next steps -{% comment %} -Provide a quick recap of what has been accomplished in the quick start as a means of transitioning to next steps. Include 2-3 actionable next steps that the user take after completing the quickstart. Always link to conceptual content on the feature or product. You can also link off to other related information on docs.github.com or in GitHub Skills. +{% comment %} +Provide a quick recap of what has been accomplished in the quick start as a means of transitioning to next steps. Include 2-3 actionable next steps that the user take after completing the quickstart. Always link to conceptual content on the feature or product. You can also link off to other related information on docs.github.com or in GitHub Skills. {% endcomment %}{% endraw %} ``` + + ## Tutorial article template Use the content model for full instructions and examples on how to write tutorials. For more information, see "[AUTOTITLE](/contributing/style-guide-and-content-model/tutorial-content-type)." + + ```yaml {% raw %}--- title: Tutorial title @@ -225,70 +243,74 @@ shortTitle: # Max 31 characters intro: 'Article intro. See tips for a great intro below' product: "{{ optional product callout }}" type: tutorial -topics: +topics: - # One or more from list of allowed topics: https://github.com/github/docs/blob/main/data/allowed-topics.js versions: - --- -{% comment %} +{% comment %} Follow the instructions in https://docs.github.com/contributing/writing-for-github-docs/content-model#quickstart to write this article. Great intros clarify who the tutorial is intended for, state what the user will accomplish, and state the technologies that will be used. -For product callout info, see https://github.com/github/docs/tree/main/content#product -For product version instructions, see https://github.com/github/docs/tree/main/content#versioning -Remove these comments from your article file when you're done writing +For product callout info, see https://github.com/github/docs/tree/main/content#product +For product version instructions, see https://github.com/github/docs/tree/main/content#versioning +Remove these comments from your article file when you're done writing {% endcomment %} - + ## Introduction -{% comment %} +{% comment %} The tutorial introduction should include the following in a short paragraph - - Clarify audience - State prerequisites and prior knowledge needed - State what the user will accomplish or build and the user problem it solves -- Link to an example of the project the user will complete +- Link to an example of the project the user will complete {% endcomment %} ## Step 1: Action the user will take -{% comment %} -In one sentence, describe what the user will do in this step -Steps should break down the tasks the user will complete in sequential order -Avoid replicating conceptual information that is covered elsewhere, provide inline links instead. Only include conceptual information unique to this use case. +{% comment %} +In one sentence, describe what the user will do in this step +Steps should break down the tasks the user will complete in sequential order +Avoid replicating conceptual information that is covered elsewhere, provide inline links instead. Only include conceptual information unique to this use case. {% endcomment %} ### Task chunk -{% comment %} -A step may require the user to perform several tasks - break those tasks down into chunks, allowing the user to scan quickly to find their place if they navigated away from this screen to perform the task. -An example might be creating a {% endraw %}{% data variables.product.pat_generic %}{% raw %} for the action to use and then storing it in secrets -For UI based tasks, include the button or options the users should click -If the task adds code, include the code in context (don't just show `needs: setup` show the entire `setup` and `dependent` jobs) +{% comment %} +A step may require the user to perform several tasks - break those tasks down into chunks, allowing the user to scan quickly to find their place if they navigated away from this screen to perform the task. +An example might be creating a {% endraw %}{% data variables.product.pat_generic %}{% raw %} for the action to use and then storing it in secrets +For UI based tasks, include the button or options the users should click +If the task adds code, include the code in context (don't just show `needs: setup` show the entire `setup` and `dependent` jobs) {% endcomment %} ### Another task chunk ## Step 2: Do the next thing -{% comment %} +{% comment %} Rinse and repeat, adding steps and tasks until the tutorial is complete -Remember to show code snippets in context +Remember to show code snippets in context {% endcomment %} ## Further reading -{% comment %} -Include a bulleted list of tutorials or articles the user can reference to extend the concepts taught in this tutorial +{% comment %} +Include a bulleted list of tutorials or articles the user can reference to extend the concepts taught in this tutorial {% endcomment %} - "[Article title](article-URL)"{% endraw %} ``` + + ## Language guides for GitHub Actions Use the content model for full instructions and examples on how to write for {% data variables.product.prodname_docs %}. For more information, see "[AUTOTITLE](/contributing/style-guide-and-content-model/about-the-content-model)." + + ```yaml {% raw %}--- title: Guide title @@ -296,21 +318,21 @@ shortTitle: # Max 31 characters intro: 'Article intro. See tips for a great intro below' product: "{{ optional product callout }}" type: tutorial -topics: +topics: - # One or more from list of allowed topics: https://github.com/github/docs/blob/main/data/allowed-topics.js versions: - --- -{% comment %} -- Great intros clarify who the guide is intended for, state what the user will accomplish, and state the technologies that will be used. +{% comment %} +- Great intros clarify who the guide is intended for, state what the user will accomplish, and state the technologies that will be used. - Intros are typically 1-3 sentence summaries, with a longer "Introduction" section that follows. - Remove these comments from your article file when you're done writing {% endcomment %} ## Introduction -{% comment %} +{% comment %} The language guide introduction should include the following in a short paragraph - - Clarify audience. - State prerequisites and prior knowledge needed. @@ -320,7 +342,7 @@ The language guide introduction should include the following in a short paragrap ## Starting with the workflow template -{% comment %} +{% comment %} Language guides typically walk through and build upon a starter workflow template. If that format doesn't work, you can include a boilerplate workflow. - Link to the GitHub Actions CI starter workflow as the boilerplate reference code and then walk through and build on that code in this guide - https://github.com/actions/starter-workflows/tree/master/ci - Provide instructions for adding the starter workflow template to a repository. @@ -329,18 +351,18 @@ Language guides typically walk through and build upon a starter workflow templat ## Running on different operating systems -{% comment %} +{% comment %} Include a brief overview of how to choose the runner environment. These should be alternatives to what operating system is presented in the starter workflow/boilerplate template. {% endcomment %} ## Configuring the version -{% comment %} +{% comment %} - Describe when and how to use available setup actions that configure the version of the language on the runner (ex. actions/setup-node). - How does the setup action configure the version and what happens when the version isn't supported in the environment. What is the default version, when no version is configured. - Include any additional features the setup action might provide that are useful to CI. - If applicable, provide examples of configuring exact versions or major/minor versions. -- Include information about software already installed on GitHub-hosted runners or software configuration necessary to build and test the project. +- Include information about software already installed on GitHub-hosted runners or software configuration necessary to build and test the project. - Provide examples of configuring matrix strategies. - Link out to any docs about available software on the GitHub-hosted runners. (Ex. https://docs.github.com/en/actions/reference/software-installed-on-github-hosted-runners). - Include code samples. @@ -348,7 +370,7 @@ Include a brief overview of how to choose the runner environment. These should b ## Installing dependencies -{% comment %} +{% comment %} - Include example of installing dependencies to prepare for building and testing. - Are there any dependencies or scenarios where people might need to install packages globally? - Include examples of common package managers. @@ -358,13 +380,13 @@ Include a brief overview of how to choose the runner environment. These should b ## Caching dependencies -{% comment %} +{% comment %} Include an example of restoring cached dependencies. We'll want to link out to the article about caching for more information (https://docs.github.com/en/actions/configuring-and-managing-workflows/caching-dependencies-to-speed-up-workflows). {% endcomment %} ## Building your code -{% comment %} +{% comment %} - Include any compile steps. - Include any test commands. - Note that you can use the same commands that your repository needs to build and test your code by simply replacing the commands in the `run` keyword. @@ -374,7 +396,9 @@ Include an example of restoring cached dependencies. We'll want to link out to t ## Packaging workflow data as artifacts -{% comment %} +{% comment %} This section can simply link out to https://docs.github.com/en/actions/configuring-and-managing-workflows/persisting-workflow-data-using-artifacts or provide additional information about which artifacts might be typical to upload for a CI workflow. {% endcomment %}{% endraw %} ``` + + diff --git a/content/pages/configuring-a-custom-domain-for-your-github-pages-site/verifying-your-custom-domain-for-github-pages.md b/content/pages/configuring-a-custom-domain-for-your-github-pages-site/verifying-your-custom-domain-for-github-pages.md index 41c650c32468..6a7d0c4a3380 100644 --- a/content/pages/configuring-a-custom-domain-for-your-github-pages-site/verifying-your-custom-domain-for-github-pages.md +++ b/content/pages/configuring-a-custom-domain-for-your-github-pages-site/verifying-your-custom-domain-for-github-pages.md @@ -16,7 +16,7 @@ When you verify your custom domain for your personal account or organization, on Verifying your domain stops other GitHub users from taking over your custom domain and using it to publish their own {% data variables.product.prodname_pages %} site. Domain takeovers can happen when you delete your repository, when your billing plan is downgraded, or after any other change which unlinks the custom domain or disables {% data variables.product.prodname_pages %} while the domain remains configured for {% data variables.product.prodname_pages %} and is not verified. -When you verify a domain, any immediate subdomains are also included in the verification. For example, if the `github.com` custom domain is verified, `docs.github.com`, `support.github.com`, and any other immediate subdomains will also be protected from takeovers. +When you verify a domain, any immediate subdomains are also included in the verification. For example, if the `github.com` custom domain is verified, `docs.github.com`, `support.github.com`, and any other immediate subdomains will also be protected from takeovers. {% data reusables.pages.wildcard-dns-warning %} diff --git a/content/site-policy/github-terms/github-corporate-terms-of-service.md b/content/site-policy/github-terms/github-corporate-terms-of-service.md index d5919cd6ce52..7fd03809c298 100644 --- a/content/site-policy/github-terms/github-corporate-terms-of-service.md +++ b/content/site-policy/github-terms/github-corporate-terms-of-service.md @@ -9,6 +9,7 @@ topics: - Policy - Legal --- + {% note %} diff --git a/content/site-policy/github-terms/github-marketplace-developer-agreement.md b/content/site-policy/github-terms/github-marketplace-developer-agreement.md index b9213f2862b6..932397b99e45 100644 --- a/content/site-policy/github-terms/github-marketplace-developer-agreement.md +++ b/content/site-policy/github-terms/github-marketplace-developer-agreement.md @@ -9,6 +9,7 @@ topics: - Policy - Legal --- + **THESE TERMS AND CONDITIONS (THE "AGREEMENT") GOVERN YOUR PARTICIPATION IN GITHUB’S MARKETPLACE PROGRAM. BY ENROLLING TO PARTICIPATE IN THE MARKETPLACE PROGRAM OR BY CLICKING “I ACCEPT” BELOW, YOU ARE CONFIRMING THAT YOU UNDERSTAND THIS AGREEMENT, AND THAT YOU ACCEPT ALL OF ITS TERMS AND CONDITIONS. IF YOU ARE ENTERING INTO THIS AGREEMENT ON BEHALF OF A COMPANY OR OTHER LEGAL ENTITY, YOU REPRESENT THAT YOU HAVE THE LEGAL AUTHORITY TO BIND THE ENTITY TO THIS AGREEMENT, IN WHICH CASE “YOU” WILL MEAN THE ENTITY YOU REPRESENT.** diff --git a/content/site-policy/github-terms/github-terms-of-service.md b/content/site-policy/github-terms/github-terms-of-service.md index b7748e1ee515..6c822f110ce1 100644 --- a/content/site-policy/github-terms/github-terms-of-service.md +++ b/content/site-policy/github-terms/github-terms-of-service.md @@ -13,6 +13,7 @@ topics: - Policy - Legal --- + Thank you for using GitHub! We're happy you're here. Please read this Terms of Service agreement carefully before accessing or using GitHub. Because it is such an important contract between us and our users, we have tried to make it as clear as possible. For your convenience, we have presented these terms in a short non-binding summary followed by the full legal terms. diff --git a/content/site-policy/privacy-policies/github-privacy-statement.md b/content/site-policy/privacy-policies/github-privacy-statement.md index daaae0c8715c..e5d00431c2d4 100644 --- a/content/site-policy/privacy-policies/github-privacy-statement.md +++ b/content/site-policy/privacy-policies/github-privacy-statement.md @@ -17,6 +17,7 @@ topics: - Policy - Legal --- + Effective date: October 10, 2023 diff --git a/content/site-policy/security-policies/github-sirt-description-rfc-2350.md b/content/site-policy/security-policies/github-sirt-description-rfc-2350.md index 730139784a80..ec1b0fe27ce6 100644 --- a/content/site-policy/security-policies/github-sirt-description-rfc-2350.md +++ b/content/site-policy/security-policies/github-sirt-description-rfc-2350.md @@ -6,6 +6,7 @@ topics: - Policy - Legal --- + ## 1. Document Information @@ -39,9 +40,9 @@ Subteams: ### 2.2 Address -GitHub SIRT -88 Colin P. Kelly Jr. St. -San Francisco, CA 94107 +GitHub SIRT +88 Colin P. Kelly Jr. St. +San Francisco, CA 94107 United States ### 2.3 Time Zone diff --git a/content/site-policy/site-policy-deprecated/amendment-to-github-terms-of-service-applicable-to-us-federal-government-users.md b/content/site-policy/site-policy-deprecated/amendment-to-github-terms-of-service-applicable-to-us-federal-government-users.md index 4567690684e2..02727e93a342 100644 --- a/content/site-policy/site-policy-deprecated/amendment-to-github-terms-of-service-applicable-to-us-federal-government-users.md +++ b/content/site-policy/site-policy-deprecated/amendment-to-github-terms-of-service-applicable-to-us-federal-government-users.md @@ -11,6 +11,7 @@ redirect_from: versions: fpt: '*' --- + _These terms apply to Customers who licensed the Products prior to January 4, 2021. Customers who purchase GitHub Products after that date are directed to https://github.com/customer-terms for current terms._ diff --git a/content/site-policy/site-policy-deprecated/github-ae-data-protection-agreement.md b/content/site-policy/site-policy-deprecated/github-ae-data-protection-agreement.md index d6bb541077b8..e3b625dcde33 100644 --- a/content/site-policy/site-policy-deprecated/github-ae-data-protection-agreement.md +++ b/content/site-policy/site-policy-deprecated/github-ae-data-protection-agreement.md @@ -8,6 +8,7 @@ redirect_from: - /github/site-policy/github-ae-data-protection-agreement - /github/site-policy-deprecated/github-ae-data-protection-agreement --- + _These terms apply to Customers who licensed the Products prior to January 4, 2021. Customers who purchase GitHub Products after that date are directed to https://github.com/customer-terms for current terms._ diff --git a/content/site-policy/site-policy-deprecated/github-ae-product-specific-terms.md b/content/site-policy/site-policy-deprecated/github-ae-product-specific-terms.md index 52ab5457051f..14ec3bcf4edd 100644 --- a/content/site-policy/site-policy-deprecated/github-ae-product-specific-terms.md +++ b/content/site-policy/site-policy-deprecated/github-ae-product-specific-terms.md @@ -8,6 +8,7 @@ redirect_from: - /github/site-policy/github-ae-product-specific-terms - /github/site-policy-deprecated/github-ae-product-specific-terms --- + _These terms apply to Customers who licensed the Products prior to January 4, 2021. Customers who purchase GitHub Products after that date are directed to https://github.com/customer-terms for current terms._ diff --git a/content/site-policy/site-policy-deprecated/github-enterprise-cloud-evaluation-agreement.md b/content/site-policy/site-policy-deprecated/github-enterprise-cloud-evaluation-agreement.md index 3f46f3bd453a..ba2e54ea1419 100644 --- a/content/site-policy/site-policy-deprecated/github-enterprise-cloud-evaluation-agreement.md +++ b/content/site-policy/site-policy-deprecated/github-enterprise-cloud-evaluation-agreement.md @@ -8,6 +8,7 @@ redirect_from: versions: fpt: '*' --- + _These terms apply to Customers who licensed the Products prior to January 4, 2021. Customers who purchase GitHub Products after that date are directed to https://github.com/customer-terms for current terms._