You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+59-76Lines changed: 59 additions & 76 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,58 @@
1
1
# Contributing to this repository <!-- omit in toc -->
2
-
We welcome contributions from the community. Read on to learn about the ways you can contribute to GitHub Docs.
2
+
3
+
## Getting started <!-- omit in toc -->
4
+
5
+
Before you begin:
6
+
- This site is powered by Node.js. Check to see if you're on the [version of node we support](contributing/development.md).
7
+
- Have you read the [code of conduct](CODE_OF_CONDUCT.md)?
8
+
- 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.
9
+
10
+
### Use the 'make a contribution' button
11
+
12
+
13
+
14
+
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.
15
+
16
+
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.
17
+
18
+
### Don't see your issue? Open one
19
+
20
+
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.
21
+
22
+
### Ready to make a change? Fork the repo
23
+
24
+
Fork using GitHub Desktop:
25
+
26
+
-[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.
27
+
- 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)!
28
+
29
+
Fork using the command line:
30
+
-[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.
31
+
32
+
### Make your update:
33
+
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).
34
+
- Are you making changes to the application code? You'll need **Node.js v14** to run the site locally. See [contributing/development.md](contributing/development.md).
35
+
- Are you contributing to markdown? We use [GitHub Markdown](contributing/content-markup-reference).
36
+
37
+
### Open a pull request
38
+
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).
39
+
40
+
### Submit your PR & get it reviewed
41
+
- 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).
42
+
- After that, we may have questions, check back on your PR to keep up with the conversation.
43
+
- 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.
44
+
45
+
### Your PR is merged!
46
+
Congratulations! The whole GitHub community thanks you. :sparkles:
47
+
48
+
Once your PR is merged, you can be added as a contributor in the [readme](README.md#contributors-).
49
+
50
+
### Keep contributing as you use GitHub Docs
51
+
52
+
Now that you're a part of the GitHub Docs community, you can keep participating in many ways.
53
+
54
+
**Learn more about contributing:**
55
+
3
56
-[Types of contributions :memo:](#types-of-contributions-memo)
4
57
-[:mega: Discussions](#mega-discussions)
5
58
-[:beetle: Issues](#beetle-issues)
@@ -26,10 +79,10 @@ We welcome contributions from the community. Read on to learn about the ways you
26
79
-[Windows](#windows)
27
80
28
81
## Types of contributions :memo:
29
-
You can contribute to the GitHub Docs content and site in several ways.
82
+
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.
30
83
31
84
### :mega: Discussions
32
-
Discussions are where we have conversations.
85
+
Discussions are where we have conversations.
33
86
34
87
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).
35
88
@@ -39,7 +92,7 @@ If you'd like help troubleshooting a docs PR you're working on, have a great new
39
92
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.
40
93
41
94
### :hammer_and_wrench: Pull requests
42
-
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.
95
+
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.
43
96
44
97
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.
45
98
@@ -66,22 +119,11 @@ You can browse existing issues to find something that needs help!
66
119
Labels can help you find an issue you'd like to help with.
67
120
- The [`good-first-issue` label](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3Agood-first-issue) is for problems or updates we think are ideal for beginners.
68
121
- 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.
69
-
- 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.
122
+
- 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.
70
123
71
124
## Opening a pull request
72
125
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.
73
126
74
-
### Fork using GitHub Desktop
75
-
[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)!
76
-
77
-
### Fork using the command line
78
-
1.[Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo#fork-an-example-repository) the repo.
79
-
2. Open the terminal.
80
-
3. Enter the following command. Use your GitHub username instead of `YOUR-USERNAME`.
81
-
```
82
-
git clone git@github.com:YOUR-USERNAME/docs
83
-
```
84
-
85
127
## Working in the github/docs repository
86
128
Here's some information that might be helpful while working on a Docs PR:
87
129
@@ -97,69 +139,10 @@ Here's some information that might be helpful while working on a Docs PR:
97
139
98
140
-[Liquid](/contribution/liquid-helpers.md) - We use liquid helpers to create different versions of our content.
99
141
100
-
-[Scripts](/script/README.md) - The scripts directory is the home for all of the scripts you can run locally.
142
+
-[Scripts](/script/README.md) - The scripts directory is the home for all of the scripts you can run locally.
101
143
102
144
-[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.
103
145
104
-
## Resolving merge conflicts
105
-
When you try to merge two branches that change the same part of the same file, you will get a merge conflict.
106
-
107
-
### In the GitHub user interface
108
-
You can resolve the merge conflicts in the [GitHub UI](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-on-github). This is useful for small conflicts, but if the conflict is more involved, you'll want to use your editor.
109
-
110
-
#### Editing the file and committing the changes
111
-
112
-
1. On the command line or GitHub Desktop, note the file that contains merge conflicts.
113
-
2. Open the file in your editor.
114
-
3. In the file, look for the merge conflict markers. (this is what it looks like in Atom)
115
-
116
-
```command-line
117
-
<<<<<<< HEAD
118
-
119
-
Here are your changes.
120
-
=====================
121
-
Here are the changes you are pulling in.
122
-
>>>>>>> main
123
-
```
124
-
4. Decide which changes to keep and delete the unwanted changes and the merge conflict markers. If there are multiple files with merge conflicts, repeat this step until you resolve all conflicts.
125
-
126
-
```command-line
127
-
Here are your changes.
128
-
```
129
-
130
-
**Note**: Resolving merge conflicts requires thought; it isn't purely mechanical and rote. Sometimes you outright accept your own changes, sometimes you take the upstream changes, and sometimes you combine the two to make a glorious hybrid update.
131
-
132
-
5. To commit your new changes:
133
-
- Using Desktop:
134
-
- Check out this [GitHub Desktop](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/committing-and-reviewing-changes-to-your-project) article.
135
-
136
-
- Using the terminal:
137
-
- Stage the file (or files) you just modified for commit.
138
-
139
-
```command-line
140
-
$ git add <EXAMPLE-CHANGED-FILE.md>
141
-
```
142
-
- Commit the file to your local branch.
143
-
144
-
```command-line
145
-
$ git commit -m "resolves merge conflicts"
146
-
```
147
-
- Push the committed changes to the remote branch of the repository on GitHub.
148
-
```command-line
149
-
$ git push origin
150
-
```
151
-
152
-
## Troubleshooting
153
-
If you get stuck while you're trying to contribute, see if someone else has had a similar problem in [discussions](https://github.com/github/docs/discussions). If not, open a new discussion!
154
-
155
-
While you're there, we'd appreciate any help answering questions you feel knowledgeable about.
156
-
157
-
### Failed status checks
158
-
If your pull request has failing status checks, [Troubleshooting](/contributing/troubleshooting.md) will walk you through some of the possible reasons.
159
-
160
-
## Draft pull requests
161
-
Do not review any [draft PRs](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests#draft-pull-requests), they're not ready! The docs team uses draft PRs to work on projects over time. When the PR is ready for feedback, we'll change the state from draft to ready for review.
162
-
163
146
## Reviewing
164
147
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.
Copy file name to clipboardExpand all lines: README.md
+25-7Lines changed: 25 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
This repository contains the documentation website code and Markdown source files for docs.github.com.
4
4
5
-
GitHub's Docs team works on pre-production content in a private repo that regularly syncs with this public repo.
5
+
GitHub's Docs team works on pre-production content in a private repo that regularly syncs with this public repo.
6
6
7
7
In this article:
8
8
-[Contributing](#contributing)
@@ -12,15 +12,33 @@ In this article:
12
12
13
13
## Contributing
14
14
15
-
:memo: To find out how you can best contribute to GitHub's product documentation, see the [CONTRIBUTING](/CONTRIBUTING.md) guide.
15
+
### Start contributing right now:
16
16
17
-
:mega: 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).
17
+
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.
18
18
19
-
:beetle: If you've found a problem, you can open an issue using a [template](https://github.com/github/docs/issues/new/choose).
19
+
#### Click **make a contribution** from docs
20
20
21
-
:question: If you're having trouble with your GitHub account, contact [Support](https://support.github.com/contact).
21
+
As you're using the GitHub Docs, you may find something in an article that you'd like to add to, update, or change. Click on **make a contribution** to navigate directly to that article in the codebase, so that you can begin making your contribution.
22
22
23
-
:yellow_heart: We do not accept pull requests for translated content - see [CONTRIBUTING.md](/CONTRIBUTING.md) for more information.
If you've found a problem, you can open an issue using a [template](https://github.com/github/docs/issues/new/choose).
28
+
29
+
#### Join us in discussions
30
+
31
+
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).
32
+
33
+
#### And that's it!
34
+
That's how you can get started easily as a member of the GitHub Documentation community. :sparkles:
35
+
36
+
If you want to know more, or you're making a more complex contribution, check out [Getting Started with Contributing](/CONTRIBUTING.md).
37
+
38
+
There are a few more things to know when you're getting started with this repo:
39
+
40
+
1. If you're having trouble with your GitHub account, contact [Support](https://support.github.com/contact).
41
+
2. We do not accept pull requests for translated content - see [CONTRIBUTING.md](/CONTRIBUTING.md) for more information.
24
42
25
43
## READMEs
26
44
@@ -99,4 +117,4 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
99
117
<!-- prettier-ignore-end -->
100
118
<!-- ALL-CONTRIBUTORS-LIST:END -->
101
119
102
-
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
120
+
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
0 commit comments