update contributing guides
This commit is contained in:
Ramya Parimi
222
CONTRIBUTING.md
222
CONTRIBUTING.md
@@ -1,180 +1,100 @@
|
||||
# Contributing to this repository <!-- omit in toc -->
|
||||
## Introduction
|
||||
|
||||
## Getting started <!-- omit in toc -->
|
||||
Thank you for your time in contributing to our project. Any contribution you make would reflect in the [docs.github.com](https://docs.github.com/en) page :sparkles:.
|
||||
|
||||
Before you begin:
|
||||
- This site is powered by Node.js. Check to see if you're on the [version of node we support](contributing/development.md).
|
||||
- Have you read the [code of conduct](CODE_OF_CONDUCT.md)?
|
||||
- Check out the [existing issues](https://github.com/github/docs/issues) & see if we [accept contributions](#types-of-contributions-memo) for your type of issue.
|
||||
This guide helps your contribution experience to be a fun and educational :confetti_ball: :book:. Read our [Code of Coduct](https://github.com/github/docs-internal/blob/main/CODE_OF_CONDUCT.md) to keep our community approachable and respectable.
|
||||
|
||||
### Use the 'make a contribution' button
|
||||
In this guide you will get an overview of the contribution workflow from opening an issue, creating a PR, reviewing and merging the PR.
|
||||
|
||||
<img src="./assets/images/contribution_cta.png" width="400">
|
||||
<!-- Use [CodeTour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) a VScode extension playback walkthroughs of how to get started with. Depends on this issue https://github.com/github/docs-team/issues/800 -->
|
||||
|
||||
Navigating a new codebase can be challenging, so we're making that a little easier. As you're using docs.github.com, you may come across an article that you want to make an update to. You can click on the **make a contribution** button right on that article, which will take you to the file in this repo where you'll make your changes.
|
||||
**Table of Contents**
|
||||
|
||||
Before you make your changes, check to see if an [issue exists](https://github.com/github/docs/issues/) already for the change you want to make.
|
||||
Use table of contents icon <img src="./assets/images/table-of-contents.png" width="25" height="25" /> on the top left corner of the this document to get to a specific section of this guide quickly.
|
||||
|
||||
### Don't see your issue? Open one
|
||||
## New Contributor Guide
|
||||
|
||||
If you spot 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 want to fix.
|
||||
[README.md](README.md) gives an overview of the project. Here are some helpful resources if you are new to open source contribution.
|
||||
|
||||
**Note:** We cannot accept contributions to the [REST API reference documentation](https://docs.github.com/en/rest/reference). If you spot an inaccuracy in the REST API reference documentation, open an issue in the [github/rest-api-description](https://github.com/github/rest-api-description/issues/new?template=schema-inaccuracy.md) repository.
|
||||
<!-- CodeTour/ codespaces intro (https://github.com/github/docs-team/issues/800) -->
|
||||
- [Finding ways to contribute to open source on GitHub](https://docs.github.com/en/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github)
|
||||
- [Set up Git](https://docs.github.com/en/get-started/quickstart/set-up-git)
|
||||
- [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow)
|
||||
- [Collaborating with pull requests](https://docs.github.com/en/github/collaborating-with-pull-requests)
|
||||
|
||||
### Ready to make a change? Fork the repo
|
||||
|
||||
You'll want to [install Git LFS](https://docs.github.com/en/github/managing-large-files/versioning-large-files/installing-git-large-file-storage).
|
||||
## Getting started
|
||||
|
||||
Fork using GitHub Desktop:
|
||||
See [Understanding the docs repository](/contributing/working-in-the-docs-repository.md) to navigate our codebase with confidence :confetti_ball:. See [GitHub Markdown](contributing/content-markup-reference.md) for information on how we write our markdown files.
|
||||
|
||||
- [Getting started with GitHub Desktop](https://docs.github.com/en/desktop/installing-and-configuring-github-desktop/getting-started-with-github-desktop) will guide you through setting up Desktop.
|
||||
- Once Desktop is set up, you can use it to [fork the repo](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/cloning-and-forking-repositories-from-github-desktop)!
|
||||
Before making changes, see what [types contributions](/contributing/types-of-contributions.md) we accept. Some of them don't require writing even a single line of code :sparkles:.
|
||||
|
||||
Fork using the command line:
|
||||
### Issues
|
||||
#### Solve an issue
|
||||
|
||||
- [Fork the repo](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo#fork-an-example-repository) so that you can make your changes without affecting the original project until you're ready to merge them.
|
||||
Scan through our [existing issues](https://github.com/github/docs/issues) to find one that interests you. You can narrow down the search using `labels` as filters. See "[Labels](/contributing/how-to-use-labels.md)" for more information.
|
||||
|
||||
Fork with [GitHub Codespaces](https://github.com/features/codespaces):
|
||||
#### Create a new issue
|
||||
|
||||
- [Fork, edit, and preview](https://docs.github.com/en/free-pro-team@latest/github/developing-online-with-codespaces/creating-a-codespace) using [GitHub Codespaces](https://github.com/features/codespaces) without having to install and run the project locally.
|
||||
If you spot an issue with the docs and if a related issue doesn't exist, you can open a new issue using a relavent [issue form](https://github.com/github/docs/issues/new/choose).
|
||||
|
||||
### Make your update:
|
||||
Make your changes to the file(s) you'd like to update. Here are some tips and tricks for [using the docs codebase](#working-in-the-githubdocs-repository).
|
||||
- Are you making changes to the application code? You'll need **Node.js v16** to run the site locally. See [contributing/development.md](contributing/development.md).
|
||||
- Are you contributing to markdown? We use [GitHub Markdown](contributing/content-markup-reference.md).
|
||||
### Make Changes
|
||||
|
||||
### Open a pull request
|
||||
When you're done making changes and you'd like to propose them for review, use the [pull request template](#pull-request-template) to open your PR (pull request).
|
||||
#### Make changes in the UI
|
||||
|
||||
### Submit your PR & get it reviewed
|
||||
- Once you submit your PR, others from the Docs community will review it with you. The first thing you're going to want to do is a [self review](#self-review).
|
||||
You can make simple changes such as a typo, sentence fix, broken link in the UI. Use **Make a contribution**
|
||||
at the bottom of any docs page to navigate directly to the `.md` file. Make your changes and [create a PR](#pull-request) for a review.
|
||||
|
||||
<img src="./assets/images/contribution_cta.png" width="300" height="150" />
|
||||
|
||||
#### Make changes locally
|
||||
|
||||
[Install Git LFS](https://docs.github.com/en/github/managing-large-files/versioning-large-files/installing-git-large-file-storage).
|
||||
|
||||
Forking repository
|
||||
- GitHub Desktop:
|
||||
- [Getting started with GitHub Desktop](https://docs.github.com/en/desktop/installing-and-configuring-github-desktop/getting-started-with-github-desktop) will guide you through setting up Desktop.
|
||||
- Once Desktop is set up, you can use it to [fork the repo](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/cloning-and-forking-repositories-from-github-desktop)!
|
||||
|
||||
- Command line:
|
||||
- [Fork the repo](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo#fork-an-example-repository) so that you can make your changes without affecting the original project until you're ready to merge them.
|
||||
|
||||
- GitHub Codespaces:
|
||||
- [Fork, edit, and preview](https://docs.github.com/en/free-pro-team@latest/github/developing-online-with-codespaces/creating-a-codespace) using [GitHub Codespaces](https://github.com/features/codespaces) without having to install and run the project locally.
|
||||
|
||||
Install/Update your to **Node.js v16**. For more information, see "[contributing/development.md](contributing/development.md)."
|
||||
|
||||
Create a working branch and start with your changes!
|
||||
### Commit your update:
|
||||
Commit the changes once you are happy with them. Here are some commonly used short and fun commit messages.
|
||||
|
||||
- :pencil2: `:pencil2:` fix typos
|
||||
- :memo: `:memo:` add or update documentation
|
||||
- :chains: `:chains:` for fixing links
|
||||
- :bug: `:bug:` for bug fix
|
||||
(Cant think of more, any ideas?)
|
||||
|
||||
Once you are ready with your changes, don't forget to [self review](/contributing/self-review.md), to quicken the review process :zap:.
|
||||
### Pull Request
|
||||
|
||||
- When you're done making the changes, open a PR (pull request).
|
||||
- Fill out the "Ready for review" template so we can review your PR. This template helps reviewers understand your changes and the purpose of your pull request.
|
||||
- Don't forget to [link PR to issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) if you are solving one.
|
||||
<!-- (This will change with the new workflow https://github.com/github/docs-team/issues/813 ) -->
|
||||
- Enable the checkbox to [allow maintainer edits](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/allowing-changes-to-a-pull-request-branch-created-from-a-fork) so the branch can be updated for a merge.
|
||||
- Once you submit your PR, one of the writers would review your proposal. Keep an eye for any questions or request for additional information.
|
||||
- We may ask for changes to be made before a PR can be merged, either using [suggested changes](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/incorporating-feedback-in-your-pull-request) or pull request comments. You can apply suggested changes directly through the UI. You can make any other changes in your fork, then commit them to your branch.
|
||||
|
||||
- As you update your PR and apply changes, mark each conversation as [resolved](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request#resolving-conversations).
|
||||
- After that, we may have questions, check back on your PR to keep up with the conversation.
|
||||
- Did you have an issue, like a merge conflict? Check out our [git tutorial](https://lab.github.com/githubtraining/managing-merge-conflicts) on how to resolve merge conflicts and other issues.
|
||||
- If you run into any merge issues, checkout this [git tutorial](https://lab.github.com/githubtraining/managing-merge-conflicts) to help you resolve merge conflicts and other issues.
|
||||
|
||||
### Your PR is merged!
|
||||
Congratulations! The whole GitHub community thanks you. :sparkles:
|
||||
Congratulations :tada::tada: The whole GitHub community thanks you :sparkles:.
|
||||
|
||||
Once your PR is merged, you will be proudly listed as a contributor in the [contributor chart](https://github.com/github/docs/graphs/contributors).
|
||||
|
||||
### Keep contributing as you use GitHub Docs
|
||||
|
||||
Now that you're a part of the GitHub Docs community, you can keep participating in many ways.
|
||||
|
||||
**Learn more about contributing:**
|
||||
|
||||
- [Types of contributions :memo:](#types-of-contributions-memo)
|
||||
- [:mega: Discussions](#mega-discussions)
|
||||
- [:beetle: Issues](#beetle-issues)
|
||||
- [:hammer_and_wrench: Pull requests](#hammer_and_wrench-pull-requests)
|
||||
- [:question: Support](#question-support)
|
||||
- [:earth_asia: Translations](#earth_asia-translations)
|
||||
- [:balance_scale: Site Policy](#balance_scale-site-policy)
|
||||
- [Starting with an issue](#starting-with-an-issue)
|
||||
- [Labels](#labels)
|
||||
- [Opening a pull request](#opening-a-pull-request)
|
||||
- [Working in the github/docs repository](#working-in-the-githubdocs-repository)
|
||||
- [Reviewing](#reviewing)
|
||||
- [Self review](#self-review)
|
||||
- [Pull request template](#pull-request-template)
|
||||
- [Suggested changes](#suggested-changes)
|
||||
- [Windows](#windows)
|
||||
|
||||
## Types of contributions :memo:
|
||||
You can contribute to the GitHub Docs content and site in several ways. This repo is a place to discuss and collaborate on docs.github.com! Our small, but mighty :muscle: docs team is maintaining this repo, to preserve our bandwidth, off topic conversations will be closed.
|
||||
|
||||
### :mega: Discussions
|
||||
Discussions are where we have conversations.
|
||||
|
||||
If you'd like help troubleshooting a docs PR you're working on, have a great new idea, or want to share something amazing you've learned in our docs, join us in [discussions](https://github.com/github/docs/discussions).
|
||||
|
||||
### :beetle: Issues
|
||||
[Issues](https://docs.github.com/en/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 content or the website that should be updated, search 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 want to fix.
|
||||
|
||||
### :hammer_and_wrench: Pull requests
|
||||
A [pull request](https://docs.github.com/en/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 should be deployed to the live site within 24 hours. :earth_africa: To learn more about opening a pull request in this repo, see [Opening a pull request](#opening-a-pull-request) below.
|
||||
|
||||
We cannot accept contributions to the [REST API reference documentation](https://docs.github.com/en/rest/reference). If you spot an inaccuracy in the REST API reference documentation, open an issue in the [github/rest-api-description](https://github.com/github/rest-api-description/issues/new?template=schema-inaccuracy.md) repository.
|
||||
|
||||
### :question: 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 GitHub, unrelated to our documentation, please [contact GitHub Support directly](https://support.github.com/contact). Any issues, discussions, or pull requests opened here requesting support will be given information about how to contact GitHub Support, then closed and locked.
|
||||
|
||||
If you're having trouble with your GitHub account, contact [Support](https://support.github.com/contact?tags=docs-contributing-guide).
|
||||
|
||||
### :earth_asia: Translations
|
||||
|
||||
This website is internationalized and available in multiple languages. The source content in this repository is written in English. We integrate with an external localization platform called [Crowdin](https://crowdin.com) and work with professional translators to localize the English content.
|
||||
|
||||
**We do not currently accept contributions for translated content**, but we hope to in the future.
|
||||
|
||||
### :balance_scale: Site Policy
|
||||
GitHub's site policies are published on docs.github.com, too!
|
||||
|
||||
If you find a typo in the site policy section, you can open a pull request to fix it. For anything else, see [the CONTRIBUTING guide in the site-policy repo](https://github.com/github/site-policy/blob/main/CONTRIBUTING.md).
|
||||
|
||||
## Starting with an issue
|
||||
You can browse existing issues to find something that needs help!
|
||||
|
||||
### Labels
|
||||
Labels can help you find an issue you'd like to help with.
|
||||
- The [`help wanted` label](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) is for problems or updates that anyone in the community can start working on.
|
||||
- The [`good first issue` label](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) is for problems or updates we think are ideal for beginners.
|
||||
- The [`content` label](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3Acontent) is for problems or updates in the content on docs.github.com. These will usually require some knowledge of Markdown.
|
||||
- The [`engineering` label](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3Aengineering) is for problems or updates in the docs.github.com website. These will usually require some knowledge of JavaScript/Node.js or YAML to fix.
|
||||
|
||||
## Opening a pull request
|
||||
You can use the GitHub user interface :pencil2: for some small changes, like fixing a typo or updating a readme. You can also fork the repo and then clone it locally, to view changes and run your tests on your machine.
|
||||
|
||||
## Working in the github/docs repository
|
||||
Here's some information that might be helpful while working on a Docs PR:
|
||||
|
||||
- [Development](/contributing/development.md) - This short guide describes how to get this app running on your local machine.
|
||||
|
||||
- [Content markup reference](/contributing/content-markup-reference.md) - All of our content is written in GitHub-flavored Markdown, with some additional enhancements.
|
||||
|
||||
- [Content style guide for GitHub Docs](/contributing/content-style-guide.md) - This guide covers GitHub-specific information about how we style our content and images. It also links to the resources we use for general style guidelines.
|
||||
|
||||
- [Content model](/contributing/content-model.md) and [content templates](/contributing/content-templates.md) - The content model describes the purpose of each type of content we use in GitHub Docs and how to write for each type. The templates allow you to quickly get started with new articles.
|
||||
|
||||
- [Reusables](/data/reusables/README.md) - We use reusables to help us keep content up to date. Instead of writing the same long string of information in several articles, we create a reusable, then call it from the individual articles.
|
||||
|
||||
- [Variables](/data/variables/README.md) - We use variables the same way we use reusables. Variables are for short strings of reusable text.
|
||||
|
||||
- [Liquid](/contributing/liquid-helpers.md) - We use liquid helpers to create different versions of our content.
|
||||
|
||||
- [Scripts](/script/README.md) - The scripts directory is the home for all of the scripts you can run locally.
|
||||
|
||||
- [Tests](/tests/README.md) - We use tests to ensure content will render correctly on the site. Tests run automatically in your PR, and sometimes it's also helpful to run them locally.
|
||||
|
||||
## Reviewing
|
||||
We (usually the docs team, but sometimes GitHub product managers, engineers, or supportocats too!) review every single PR. The purpose of reviews is to create the best content we can for people who use GitHub.
|
||||
|
||||
:yellow_heart: Reviews are always respectful, acknowledging that everyone did the best possible job with the knowledge they had at the time.
|
||||
:yellow_heart: Reviews discuss content, not the person who created it.
|
||||
:yellow_heart: Reviews are constructive and start conversation around feedback.
|
||||
|
||||
### Self review
|
||||
You should always review your own PR first.
|
||||
|
||||
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).
|
||||
- [ ] Compare your pull request's source changes to staging to confirm that the output matches the source and that everything is rendering as expected. This helps spot issues like typos, content that doesn't follow the style guide, or content that isn't rendering due to versioning problems. Remember that lists and tables can be tricky.
|
||||
- [ ] Review the content for technical accuracy.
|
||||
- [ ] Review the entire pull request using the [localization checklist](contributing/localization-checklist.md).
|
||||
- [ ] Copy-edit the changes for grammar, spelling, and adherence to the [style guide](https://github.com/github/docs/blob/main/contributing/content-style-guide.md).
|
||||
- [ ] Check new or updated Liquid statements to confirm that versioning is correct.
|
||||
- [ ] If there are any failing checks in your PR, troubleshoot them until they're all passing.
|
||||
|
||||
### Pull request template
|
||||
When you open a pull request, you must fill out the "Ready for review" template before we can review your PR. This template helps reviewers understand your changes and the purpose of your pull request.
|
||||
|
||||
### Suggested changes
|
||||
We may ask for changes to be made before a PR can be merged, either using [suggested changes](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/incorporating-feedback-in-your-pull-request) or pull request comments. You can apply suggested changes directly through the UI. You can make any other changes in your fork, then commit them to your branch.
|
||||
|
||||
As you update your PR and apply changes, mark each conversation as [resolved](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request#resolving-conversations).
|
||||
Now that you are part of the GitHub docs community, see what other ways you [contribute to the docs](/contributing/types-of-contributions.md).
|
||||
|
||||
## Windows
|
||||
|
||||
|
||||
41
README.md
41
README.md
@@ -4,47 +4,36 @@ This repository contains the documentation website code and Markdown source file
|
||||
|
||||
GitHub's Docs team works on pre-production content in a private repo that regularly syncs with this public repo.
|
||||
|
||||
In this article:
|
||||
|
||||
- [Contributing](#contributing)
|
||||
- [READMEs](#readmes)
|
||||
- [License](#license)
|
||||
## Table of contents
|
||||
|
||||
Use the table of contents icon <img src="./assets/images/table-of-contents.png" width="25" height="25" /> on the top left corner of the this document to get to a specific section of this guide quickly.
|
||||
## Contributing
|
||||
|
||||
### Start contributing right now:
|
||||
See our [CONTRIBUTING.md](CONTRIBUTING.md) for detailed instructions of how to get started with our project.
|
||||
<!-- info about codetour/codespaces (https://github.com/github/docs-team/issues/800) -->
|
||||
|
||||
We accept a lot of [different contributions](CONTRIBUTING.md/#types-of-contributions-memo), including some that don't require you to write a single line of code.
|
||||
We accept different [types of contributions](CONTRIBUTING.md/#types-of-contributions-memo), including some that don't require you to write a single line of code.
|
||||
|
||||
#### Click **make a contribution** from docs
|
||||
|
||||
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.
|
||||
For quick fixes like typos, updates, link fixes etc., use **make a contribution** to make changes and submit a PR.
|
||||
|
||||
<img src="./assets/images/contribution_cta.png" width="400">
|
||||
|
||||
#### Open an issue
|
||||
**Open an issue** using an [issue template](https://github.com/github/docs/issues/new/choose).
|
||||
|
||||
If you've found a problem, you can open an issue using a [template](https://github.com/github/docs/issues/new/choose).
|
||||
**Solve an issue** by first scanning through our [existing issues](https://github.com/github/docs/issues). When ready, check out [Getting Started with Contributing](/CONTRIBUTING.md) for detailed instructions.
|
||||
|
||||
#### Solve an issue
|
||||
|
||||
If you have a solution to one of the open issues, you will need to fork the repository and submit a pull request using the [template](https://github.com/github/docs/blob/main/CONTRIBUTING.md#pull-request-template) that is visible automatically in the pull request body. For more details about this process, please check out [Getting Started with Contributing](/CONTRIBUTING.md).
|
||||
|
||||
#### Join us in discussions
|
||||
### Join us in discussions
|
||||
|
||||
We use GitHub Discussions to talk about all sorts of topics related to documentation and this site. For example: if you'd like help troubleshooting a PR, have a great new idea, or want to share something amazing you've learned in our docs, join us in [discussions](https://github.com/github/docs/discussions).
|
||||
|
||||
#### And that's it!
|
||||
### And that's it!
|
||||
|
||||
That's how you can get started easily as a member of the GitHub Documentation community. :sparkles:
|
||||
If you're having trouble with your GitHub account, contact [Support](https://support.github.com/contact).
|
||||
|
||||
That's how you can easily become a member of the GitHub Documentation community. :sparkles:
|
||||
|
||||
If you want to know more, or you're making a more complex contribution, check out [Getting Started with Contributing](/CONTRIBUTING.md).
|
||||
|
||||
There are a few more things to know when you're getting started with this repo:
|
||||
|
||||
1. If you're having trouble with your GitHub account, contact [Support](https://support.github.com/contact).
|
||||
2. We do not accept pull requests for translated content - see [CONTRIBUTING.md](/CONTRIBUTING.md) for more information.
|
||||
|
||||
## READMEs
|
||||
|
||||
In addition to the README you're reading right now, this repo includes other READMEs that describe the purpose of each subdirectory in more detail:
|
||||
@@ -72,3 +61,7 @@ The GitHub product documentation in the assets, content, and data folders are li
|
||||
All other code in this repository is licensed under a [MIT license](LICENSE-CODE).
|
||||
|
||||
When using the GitHub logos, be sure to follow the [GitHub logo guidelines](https://github.com/logos).
|
||||
|
||||
## Thanks :purple_heart:
|
||||
|
||||
Thanks for all your contributions and efforts towards the GitHub documentation. We thank you being part of our enormous community!!
|
||||
|
||||
BIN
assets/images/table-of-contents.png
Normal file
BIN
assets/images/table-of-contents.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
@@ -20,23 +20,24 @@ See the [contributing docs](/CONTRIBUTING.md) for general information about work
|
||||
- [`showMiniToc`](#showminitoc)
|
||||
- [`miniTocMaxHeadingLevel`](#minitocmaxheadinglevel)
|
||||
- [`allowTitleToDifferFromFilename`](#allowtitletodifferfromfilename)
|
||||
- [`changelog`](#changelog)
|
||||
- [`defaultPlatform`](#defaultplatform)
|
||||
- [`defaultTool`](#defaulttool)
|
||||
- [`learningTracks`](#learningTracks)
|
||||
- [`includeGuides`](#includeGuides)
|
||||
- [`learningTracks`](#learningtracks)
|
||||
- [`includeGuides`](#includeguides)
|
||||
- [`type`](#type)
|
||||
- [`topics`](#topics)
|
||||
- [`contributor`](#contributor)
|
||||
- [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)
|
||||
- [Free-pro-team vs. GitHub.com versioning](#free-pro-team-vs-githubcom-versioning)
|
||||
- [Filenames](#filenames)
|
||||
- [Whitespace control](#whitespace-control)
|
||||
- [Links and image paths](#links-and-image-paths)
|
||||
- [Preventing transformations](#preventing-transformations)
|
||||
- [Index pages](#index-pages)
|
||||
- [Creating new sublanding pages](#creating-new-sublanding-pages)
|
||||
- [Index pages](#index-pages)
|
||||
- [Creating new sublanding pages](#creating-new-sublanding-pages)
|
||||
|
||||
## Frontmatter
|
||||
|
||||
@@ -112,6 +113,12 @@ See [`contributing/redirects`](contributing/redirects.md) for more info.
|
||||
- Type: `String`
|
||||
- Optional. If omitted, `title` will be used.
|
||||
|
||||
|Article type |Maximum character length |
|
||||
--- | --- |
|
||||
|articles | 31 |
|
||||
|categories |27 |
|
||||
|map topics |30 |
|
||||
|
||||
Example:
|
||||
|
||||
```yaml
|
||||
|
||||
@@ -31,6 +31,7 @@ These guidelines are specific to GitHub’s documentation. For general style que
|
||||
- [Reusables and variables](#reusables-and-variables)
|
||||
- [Tables](#tables)
|
||||
- [Titles](#titles)
|
||||
- [Short titles](#short-titles)
|
||||
- [User interface elements](#user-interface-elements)
|
||||
- [Boldface](#boldface)
|
||||
- [Branch names](#branch-names)
|
||||
@@ -305,6 +306,20 @@ Use quotation marks around article titles, whether the article is hosted on GitH
|
||||
|
||||
For further guidance, see “[Formatting titles](https://docs.microsoft.com/style-guide/text-formatting/formatting-titles)” in Microsoft’s Style Guide.
|
||||
|
||||
## Short titles
|
||||
|
||||
- Length should be 2-3 words.
|
||||
- Look contextually to see what to omit and how the full breadcrumb looks like.
|
||||
- Has to convey full meaning of the title and content of the category or map topic
|
||||
- :scissors: repeated words when possible
|
||||
- Short titles should be parallel to short titles for other similar content
|
||||
- e.g. `Organizations and teams`, `Enterprise accounts`
|
||||
- Short titles should still mimic format of title
|
||||
- For task-based titles, if there’s a preposition or object or it’s otherwise awkward to shorten, can use a noun sparingly, try to find a verb form
|
||||
- e.g. Authenticating to GitHub :arrow_right: Authentication
|
||||
- Installing and configuring GHE Server :arrow_right: Installation and configuration
|
||||
- Don’t introduce new words in short titles that aren’t in the full title
|
||||
|
||||
## User interface elements
|
||||
|
||||
### Boldface
|
||||
|
||||
6
contributing/how-to-use-labels.md
Normal file
6
contributing/how-to-use-labels.md
Normal file
@@ -0,0 +1,6 @@
|
||||
### Labels
|
||||
Labels can help you find an issue you'd like to help with.
|
||||
- The [`help wanted` label](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) is for problems or updates that anyone in the community can start working on.
|
||||
- The [`good first issue` label](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) is for problems or updates we think are ideal for beginners.
|
||||
- The [`content` label](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3Acontent) is for problems or updates in the content on docs.github.com. These will usually require some knowledge of Markdown.
|
||||
- The [`engineering` label](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3Aengineering) is for problems or updates in the docs.github.com website. These will usually require some knowledge of JavaScript/Node.js or YAML to fix.
|
||||
36
contributing/types-of-contributions.md
Normal file
36
contributing/types-of-contributions.md
Normal file
@@ -0,0 +1,36 @@
|
||||
## Types of contributions :memo:
|
||||
You can contribute to the GitHub Docs content and site in several ways. This repo is a place to discuss and collaborate on docs.github.com! Our small, but mighty :muscle: docs team is maintaining this repo, to preserve our bandwidth, off topic conversations will be closed.
|
||||
|
||||
### :mega: Discussions
|
||||
Discussions are where we have conversations.
|
||||
|
||||
If you'd like help troubleshooting a docs PR you're working on, have a great new idea, or want to share something amazing you've learned in our docs, join us in [discussions](https://github.com/github/docs/discussions).
|
||||
|
||||
### :beetle: Issues
|
||||
[Issues](https://docs.github.com/en/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 content or the website that should be updated, search 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 want to fix.
|
||||
|
||||
### :hammer_and_wrench: Pull requests
|
||||
A [pull request](https://docs.github.com/en/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 should be deployed to the live site within 24 hours. :earth_africa: To learn more about opening a pull request in this repo, see [Opening a pull request](#opening-a-pull-request) below.
|
||||
|
||||
We cannot accept contributions to the [REST API reference documentation](https://docs.github.com/en/rest/reference). If you spot an inaccuracy in the REST API reference documentation, open an issue in the [github/rest-api-description](https://github.com/github/rest-api-description/issues/new?template=schema-inaccuracy.md) repository.
|
||||
|
||||
### :question: 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 GitHub, unrelated to our documentation, please [contact GitHub Support directly](https://support.github.com/contact). Any issues, discussions, or pull requests opened here requesting support will be given information about how to contact GitHub Support, then closed and locked.
|
||||
|
||||
If you're having trouble with your GitHub account, contact [Support](https://support.github.com/contact?tags=docs-contributing-guide).
|
||||
|
||||
### :earth_asia: Translations
|
||||
|
||||
This website is internationalized and available in multiple languages. The source content in this repository is written in English. We integrate with an external localization platform called [Crowdin](https://crowdin.com) and work with professional translators to localize the English content.
|
||||
|
||||
**We do not currently accept contributions for translated content**, but we hope to in the future.
|
||||
|
||||
### :balance_scale: Site Policy
|
||||
GitHub's site policies are published on docs.github.com, too!
|
||||
|
||||
If you find a typo in the site policy section, you can open a pull request to fix it. For anything else, see [the CONTRIBUTING guide in the site-policy repo](https://github.com/github/site-policy/blob/main/CONTRIBUTING.md).
|
||||
|
||||
Reference in New Issue
Block a user