How we docs megabranch (#36788)

Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Co-authored-by: hubwriter <hubwriter@github.com>
Co-authored-by: github-actions <github-actions@github.com>
Co-authored-by: Laura Coursen <lecoursen@github.com>
Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>
Co-authored-by: Sophie <29382425+sophietheking@users.noreply.github.com>
Co-authored-by: Anne-Marie <102995847+am-stead@users.noreply.github.com>
Co-authored-by: Kevin Heis <heiskr@users.noreply.github.com>
Co-authored-by: Isaac Brown <101839405+isaacmbrown@users.noreply.github.com>
Co-authored-by: Robert Sese <734194+rsese@users.noreply.github.com>
Co-authored-by: Ben Ahmady <32935794+subatoi@users.noreply.github.com>
Co-authored-by: Peter Bengtsson <peterbe@github.com>
Co-authored-by: Siara <108543037+SiaraMist@users.noreply.github.com>

content/contributing/collaborating-on-github-docs/about-contributing-to-github-docs.md

@@ -0,0 +1,80 @@
+---
+title: About contributing to GitHub Docs
+shortTitle: About contributing
+intro: 'You can contribute to GitHub Docs content in several ways.'
+product: '{% data reusables.contributing.product-note %}'
+versions:
+  feature: 'contributing'
+---
+
+{% 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](/).
+
+{% ifversion discussions %}
+
+## Discussions
+
+[Discussions](/discussions/quickstart) are where we have conversations.
+
+If you'd like help troubleshooting a documentation issue or pull request you're working on, have a great new idea for documentation, or want to share something amazing you've learned in our docs, join us in the [`docs` repository discussions](https://github.com/github/docs/discussions).
+
+{% note %}
+
+**Note**: To preserve the bandwidth of the Docs team, off-topic conversations will be closed.
+
+{% endnote %}
+
+{% endif %}
+
+## Issues
+
+[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.
+
+{% note %}
+
+**Note**: {% data variables.product.prodname_dotcom %} employees should open issues in the private `docs-content` repository.
+
+{% endnote %}
+
+## Pull requests
+
+A [pull request](/github/collaborating-with-issues-and-pull-requests/about-pull-requests) is a way to suggest changes in our repository. When we merge those changes, they're deployed to the live site within 24 hours.
+
+We cannot accept contributions to the [REST API reference documentation](/rest/reference). If you spot an inaccuracy in the REST API reference documentation, open an issue in the [`rest-api-description`](https://github.com/github/rest-api-description/issues/new?template=schema-inaccuracy.md) repository.
+
+### Reviewing your own pull requests
+
+You should always review your own pull request first, before marking it as ready for review by others.
+
+For content changes, make sure that you:
+
+- Confirm that the changes meet the user experience and goals outlined in the content design plan (if there is one).
+- Review the content for technical accuracy.
+- Check your changes for grammar, spelling, and adherence to the [style guide](https://github.com/github/docs/blob/main/contributing/content-style-guide.md).
+- Make sure the text in your pull request will be easy to translate. For more information, see "[Translations guide for writers](https://github.com/github/docs/blob/main/contributing/translations-for-writers.md)."
+- Check new or updated Liquid statements to confirm that versioning is correct. For more information, see "[Liquid helpers](https://github.com/github/docs/blob/main/contributing/liquid-helpers.md)."
+- Check the preview of any pages you have changed. A preview is automatically generated after you submit a pull request and links are added to the pull request. The preview sometimes takes several minutes before it is ready to view. Confirm that everything is rendering as expected. Checking the preview will help you identify problems such as typos, content that doesn't follow the style guide, or content that isn't rendering due to versioning problems. Make sure to check the rendered output for lists and tables, which can sometimes have problems that are difficult to identify in the Markdown.
+- If there are any failing checks in your pull request, troubleshoot them until they're all passing.
+
+## Support
+
+We are a small team working hard to keep up with the documentation demands of a continuously changing product. Unfortunately, we just can't help with support questions in this repository. If you are experiencing a problem with {% data variables.product.prodname_dotcom %}, unrelated to our documentation, please [contact {% data variables.product.prodname_dotcom %} Support directly](https://support.github.com/contact). Any issues{% ifversion discussions %}, discussions,{% endif %} or pull requests opened in the documentation repository requesting support will be given information about how to contact {% data variables.product.prodname_dotcom %} Support, then closed and locked.
+
+If you're having trouble with your {% data variables.product.prodname_dotcom %} account, contact [Support](https://support.github.com/contact?tags=docs-contributing-guide).
+
+## Translations
+
+This website is internationalized and available in multiple languages. The source content in this repository is written in English. We automate translations through an internal process, working with professional translators to localize the English content.
+
+If you spot a translation error, please raise an issue with the details.
+
+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.
+
+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.

content/contributing/collaborating-on-github-docs/index.md

@@ -0,0 +1,13 @@
+---
+title: Collaborating on GitHub Docs
+shortTitle: Collaborate on GitHub Docs
+intro: 'Find out about collaborating on GitHub Docs.'
+product: '{% data reusables.contributing.product-note %}'
+versions:
+  feature: 'contributing'
+children:
+  - /about-contributing-to-github-docs
+  - /using-git-on-github-docs
+  - /using-the-todocs-placeholder-to-leave-notes
+  - /label-reference
+---

content/contributing/collaborating-on-github-docs/label-reference.md

@@ -0,0 +1,17 @@
+---
+title: Label reference
+intro: "Labels can help you find an issue you'd like to help with."
+product: '{% data reusables.contributing.product-note %}'
+versions:
+  feature: 'contributing'
+---
+
+You can use labels to locate a particular type of issue. For example, click the labels in the table to see a filtered list of open issues in the github/docs repository.
+
+| Label | Description |
+| --- | --- |
+| [`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. | 
+| [`codespaces`](https://github.com/github/docs/labels/codespaces)<br> [`desktop`](https://github.com/github/docs/labels/desktop)<br> [`graphql`](https://github.com/github/docs/labels/graphql) | Labels for filtering issues by a product or documentation area. | 

content/contributing/collaborating-on-github-docs/using-git-on-github-docs.md

@@ -0,0 +1,205 @@
+---
+title: Using Git on GitHub Docs
+shortTitle: Using Git
+intro: 'You can use Git on the command line to commit changes and then push them to the documentation repository.'
+product: '{% data reusables.contributing.product-note %}'
+versions:
+  feature: 'contributing'
+---
+
+This article describes the process of creating a topic branch for the documentation repository, committing changes, and pushing your changes back up to the remote repository.
+
+The article assumes you have already cloned the documentation repository locally and you will be making changes on your local computer rather than on {% data variables.product.prodname_dotcom_the_website %} or in a codespace. For more information, see "[AUTOTITLE](/repositories/creating-and-managing-repositories/cloning-a-repository?tool=webui)."
+
+## Setting up your topic branch and making changes
+
+To keep your local branches in sync with their remotes and avoid merge conflicts, follow these steps as you work on documentation.
+
+1. In the terminal, change the current working directory to the location where you cloned the documentation repository. For example:
+
+   ```
+   cd ~/my-cloned-repos/docs
+   ```
+
+1. Switch to the default branch: `main`.
+
+   ```
+   git checkout main
+   ```
+
+1. Get the most recent commits from the remote repository.
+
+   ```
+   git pull origin main
+   ```
+
+1. Switch to or create a topic branch.
+   - To start a new project, create a new topic branch from `main`.
+
+     ```
+     git checkout -b YOUR-TOPIC-BRANCH
+     ```
+
+     {% note %}
+
+     **Note**: You can use forward slashes as part of the branch name, for example to include your user name:
+
+     ```
+     git checkout -b my-username/new-codespace-policy
+     ```     
+
+     {% endnote %}
+
+   - To work on an existing project, switch to your topic branch and merge changes from `main`.
+
+     ```
+     git checkout YOUR-TOPIC-BRANCH
+     git merge main
+     ```
+
+     If you run into merge conflicts, follow the steps later in this article for [resolving merge conflicts](#resolving-merge-conflicts).
+
+1. Open your preferred text editor, edit files as required, then save your changes.
+
+## Committing and pushing your changes
+
+1. When you're ready to commit your changes, open a terminal and check the status of your topic branch with `git status`. Make sure you see the correct set of changes.
+
+   ```
+   git status
+   On branch YOUR-TOPIC-BRANCH
+
+   Changes not staged for commit:
+     (use "git add <file>..." to update what will be committed)
+     (use "git checkout -- <file>..." to discard changes in working directory)
+           deleted:    example-deleted-file.md
+           modified:   example-changed-file.md
+
+   Untracked files:
+     (use "git add <file>..." to include in what will be committed)
+           example-new-file.md
+   ```
+
+1. Stage the changed files so that they're ready to be committed to your topic branch.
+
+   - If you created new files or updated existing files, use `git add FILENAME [FILENAME...]`. For example:
+
+     ```
+     git add example-new-file.md example-changed-file.md
+     ```
+
+     This adds the updated version of the files to Git's staging area, from which changes can be committed. To unstage a file, use `git reset HEAD FILENAME`. For example, `git reset HEAD example-changed-file.md`.
+
+   - If you deleted files, use `git rm FILENAME [FILENAME...]`. For example:
+
+     ```
+     git rm example-deleted-file.md
+     ```
+
+1. Commit your changes.
+
+   ```
+   git commit -m "Commit message title (max 72 characters)
+
+   Optional fuller description of what changed (no character limit). 
+   Note the empty line between the title and the description, 
+   and the closing quotation mark at the end of the commit message."
+   ```
+
+   This commits the staged changes locally. You can now push this commit, and any other unpushed commits, to the remote repository.  
+   
+   To remove this commit, use `git reset --soft HEAD~1`. After running this command our changes are no longer committed but the changed files remain in the staging area. You can make further changes and then `add` and `commit` again.
+
+1. Push your changes to the remote repository on {% data variables.product.prodname_dotcom_the_website %}.
+
+   - The first time you push your branch you can choose to add an upstream tracking branch. This allows you to use `git pull` and `git push` on that branch without additional arguments.
+
+     ```
+     git push --set-upstream origin YOUR-TOPIC-BRANCH
+     ```
+
+   - If you've pushed this branch before, and set an upstream tracking branch you can use:
+
+     ```
+     git push
+     ```
+
+### Best practices for commits
+
+- Favor commits that contain small, focused groups of changes over commits with large, unfocused groups of changes, since this will help you write commit messages that other people can easily understand. An exception is the initial commit for a new project or category. These commits are sometimes large, as they often introduce the bare versions of many articles at once to provide an organizational scheme for subsequent work.
+- If you are incorporating feedback or want to address a set of changes to a particular person or team for review, @mention the person whose suggestions you are incorporating. For example: "Incorporating feedback from @octocat," or "Updating billing configuration steps - cc @monalisa for accuracy."
+- If a commit addresses an issue, you can reference the issue number in the commit, and a link to the commit will appear in the issue conversation timeline: "Addresses #1234 - adds steps for backing up the VM before upgrading." 
+  {% note %}
+
+  **Note**: We generally don't close an issue via a commit. To close an issue, open a pull request and add "Closes #1234" to the description. The linked issue will be closed when the pull request is merged. For more information, see "[AUTOTITLE](/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)."
+
+  {% endnote %}
+- Make commit messages clear, detailed, and imperative. For example: "Adds a conceptual article about 2FA," not "Add info."
+- Try not to leave uncommitted changes in your local branch when you finish working for the day. Get to a good stopping point and commit and push your changes so your work is backed up to the remote repository.
+- Only push up to {% data variables.product.prodname_dotcom_the_website %} after you've made a few commits. Pushing after every commit adds noise to our ops channels on Slack and causes unnecessary builds to run.
+
+## Resolving merge conflicts
+
+When you try to merge two branches that contain different changes to the same part of a file, you will get a merge conflict. In our workflow, this most often occurs when merging `main` down into a local topic branch.
+
+There are two ways to handle merge conflicts:
+- Edit the file in your text editor and choose which changes to keep. Then commit the updated file to your topic branch from the command line.
+- [Resolve the merge conflicts on {% data variables.product.prodname_dotcom_the_website %}](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github).
+
+### Resolving merge conflicts by editing the file and committing the changes
+
+1. On the command line, note the files that contains merge conflicts.
+1. Open the first of these files in your text editor.
+1. In the file, look for the merge conflict markers.
+
+   ```
+   <<<<<<< HEAD
+   Here are the changes you've made.
+   =====================
+   Here are the changes from the main branch.
+   >>>>>>> main
+   ```
+
+1. Decide which changes to keep and delete the unwanted changes and the merge conflict markers. If you need to make further changes, you can do so at the same time. For example, you could change the five lines shown in the previous code sample to the single line:
+
+   ```
+   Here are the changes you want to use.
+   ```
+
+   If there are multiple files with merge conflicts, repeat the previous steps until you resolve all conflicts.
+
+   {% note %}
+
+   **Note**: You should apply care when resolving merge conflicts. Sometimes you will simply accept your own changes, sometimes you will use the upstream changes from the `main` branch, and sometimes you will combine both sets of changes. If you're unsure of the best resolution, be wary of replacing the changes from upstream as these may have been made for specific reasons that you're not aware of.
+
+   {% endnote %}
+
+1. In the terminal, stage the file, or files, that you just modified.
+
+   ```
+   git add changed-file-1.md changed-file-2.md
+   ```
+
+1. Commit the files.
+
+   ```
+   git commit -m "Resolves merge conflicts"
+   ```
+
+1. Push the committed changes to the remote repository on {% data variables.product.prodname_dotcom_the_website %}.
+
+   ```
+   git push
+   ```
+
+## Creating a pull request
+
+We recommend you open your pull request on {% data variables.product.prodname_dotcom %} early. Create the pull request as a draft until you are ready for it to be reviewed. Each time you push changes, your commits will be added to the pull request.
+
+{% note %}
+
+**Note**: You can quickly access pull requests you've created by clicking **Pull requests** at the top of every page on {% data variables.product.prodname_dotcom_the_website %}.
+
+{% endnote %}
+
+For more information, see "[AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request?tool=webui#creating-the-pull-request)."

content/contributing/collaborating-on-github-docs/using-the-todocs-placeholder-to-leave-notes.md

@@ -0,0 +1,30 @@
+---
+title: Using the TODOCS placeholder to leave notes
+shortTitle: Using the TODOCS placeholder
+intro: 'You can use the `TODOCS` placeholder to indicate work that still needs to be completed.'
+product: '{% data reusables.contributing.product-note %}'
+versions:
+  feature: 'contributing'
+---
+
+## Using the TODOCS placeholder
+
+Sometimes technical writers use placeholders while writing documentation to remind themselves to come back to something later. It's a useful technique, but there's always the possibility that the placeholder will be overlooked and slip into production. At that point, the only way the Docs team will find out about it is if someone sees it and reports it.
+
+To prevent slips, use the string `TODOCS` as your placeholder. The Docs test suite includes a [linting test](https://github.com/github/docs/tree/main/src/content-linter) that will fail if it finds this string anywhere in a Markdown or YAML file.
+
+{% note %}
+
+**Note**: If you use {% data variables.product.prodname_vscode_shortname %} as your text editor, the "[TODO Highlight](https://marketplace.visualstudio.com/items?itemName=wayou.vscode-todo-highlight)" extension is useful for highlighting instances of "TODOCS" in your files. Add "TODOCS" and other varieties of casing, such as "todocs," to the settings for this extension.
+
+{% endnote %}
+
+### Example
+
+```
+1. In the dropdown, select the settings you want to sync.
+
+   TODOCS: ADD A SCREENSHOT OF THE SETTINGS SYNC OPTIONS
+
+1. Click **Sign in & Turn on**, then select the account to which you want your settings to be synced.
+```

content/contributing/index.md

@@ -0,0 +1,14 @@
+---
+title: Contributing to GitHub Docs
+shortTitle: Contribute to GitHub Docs
+intro: 'Learn about how the {% data variables.product.prodname_docs %} team creates documentation and how you can contribute.'
+layout: product-landing
+product: '{% data reusables.contributing.product-note %}'
+versions:
+  feature: 'contributing'
+children:
+  - /writing-for-github-docs
+  - /syntax-and-versioning-for-github-docs
+  - /collaborating-on-github-docs
+  - /setting-up-your-environment-to-work-on-github-docs
+---