Skip to content

Commit a42958c

Browse files
Apply suggestions from code review
Co-authored-by: JC Palmer <me@jccpalmer.com>
1 parent e70a6b1 commit a42958c

1 file changed

Lines changed: 36 additions & 20 deletions

File tree

CONTRIBUTING.md

Lines changed: 36 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22

33
Thank you for helping us make this project great and being a part of the Solid community!
44

5-
We welcome contributions from anyone, regardless of your skill level of the size of the contribution. We are happy to help with guidance on PRs, technical writing, and turning features into realities.
5+
We welcome contributions from anyone, regardless of your skill level.
6+
We are happy to help with guidance on PRs, technical writing, and turning features into realities.
67

78
> **New to contributing?**
89
Take a look at [this GitHub guide](https://docs.github.com/en/get-started/quickstart/hello-world) to learn how to use Git and GitHub to contribute to open-source.
@@ -12,11 +13,15 @@ If you're new to Solid, we ask that you check out our [Writing Guide](https:/
1213
## Types of contributions
1314
There are many ways to contribute to the Solid's documentation!
1415

15-
The Solid Docs website is built on Solid! Maintaining it requires not only written content but also maintaining the Solid code, addressing a11y, CSS, UI, and UX concerns. We also aim to make our documentation available in several languages, so we need help translating the entire site.
16+
The Solid Docs website is built on Solid!
17+
Maintaining it requires not only written content and Solid code maintenance, but it also needs to address accessibility (a11y), CSS, UI, and UX concerns.
18+
We also aim to make our documentation available in several languages, so we need help translating the entire site.
1619

17-
You can help out by getting involved by leaving review comments on [PRs](https://github.com/solidjs/solid-docs-next/pulls) and adding ideas in existing GitHub [issues ](https://github.com/solidjs/solid-docs-next/issues)and [discussions](https://github.com/solidjs/solid-docs-next/discussions).
20+
You can help out by leaving review comments on [PRs](https://github.com/solidjs/solid-docs-next/pulls) and adding ideas in existing GitHub [issues ](https://github.com/solidjs/solid-docs-next/issues) and [discussions](https://github.com/solidjs/solid-docs-next/discussions).
1821

19-
Every PR, especially translation PRs, will need reviewers. Reviewing PRs and leaving comments, suggestions, or even saying "looks good!" can be a great way to get started on contributing alongside our Docs team, and to learn more about Solid.
22+
Every PR, especially translation PRs, will need reviewers.
23+
Reviewing PRs and leaving comments, suggestions, or even saying "Looks good!" can be a great way to get started on contributing alongside our Docs team.
24+
It's also a great way to learn more about Solid!
2025

2126
We encourage you to:
2227

@@ -30,9 +35,9 @@ Issues are a great way to keep track of tasks, enhancements, and bugs for our pr
3035

3136
After an issue has been considered by the community, we often reach out to community members to encourage them to submit PRs based on existing issues.
3237

33-
Larger contributions to the docs are encouraged after participating in Issues and Discussions, as unsolicited material may not fit into our existing plans.
38+
We encourage larger contributions to the docs after you participate in Issues and Discussions, as unsolicited material may not fit into our existing plans.
3439

35-
> While you're more than welcomed to mention a bug you've encountered on our Discord, we ask that you also report it as an issue!
40+
> While you're more than welcome to mention a bug that you've encountered on our Discord, we ask that you also report it as an issue!
3641
3742
### Writing an issue
3843
Helpful issues generally include:
@@ -42,7 +47,7 @@ Helpful issues generally include:
4247
- Explanations as to why (or _for whom_) this is a problem
4348
- _Option_: proposed solutions
4449
### Examples of helpful new issues
45-
- An explanation is confusing (with an explanation as to why)
50+
- An explanation is confusing (with a reason why)
4651
- a code example is wrong (with or without a proposed fix)
4752
- accessibility (a11y) issues discovered
4853
- missing content
@@ -56,7 +61,8 @@ We use labels as a way to organize and categorize our issues. Here are some comm
5661
- `help wanted` - when we are looking for assistance on an issue
5762
- `i18n` - anything to do with internationalization and translation
5863
## Start a discussion
59-
Discussion are a place within this repository where we can have open-ended conversations. It's the perfect place for Q&A, sharing ideas, community engagement, and connecting with other members.
64+
Discussions are a place within this repository where we can have open-ended conversations.
65+
It's the perfect place for Q&A, sharing ideas, community engagement, and connecting with other members.
6066

6167
Feel free to start a [new discussion](https://github.com/solidjs/solid-docs-next/discussions) on any topic related to our docs!
6268

@@ -66,14 +72,15 @@ Feel free to start a [new discussion](https://github.com/solidjs/solid-docs-n
6672
- Is the site navigation clear and helpful?
6773
- Any suggestions of content that you think could be helpful adding
6874
## Make a PR (Pull Request)
69-
> If you've never submitted a pull request on GitHub before, check out [this overview](https://opensource.guide/how-to-contribute/#opening-a-pull-request).
75+
> If you've never submitted a pull request on GitHub before, check out [this overview on how to open a PR](https://opensource.guide/how-to-contribute/#opening-a-pull-request).
7076
71-
PRs are the heart of collaboration on GitHub. When you open a pull request, you are putting forward your suggested changes, inviting us to review it, and requesting for these changes to be merged into our main branch.
77+
PRs are the heart of collaboration on GitHub.
78+
When you open a pull request, you are putting forward your suggested changes, inviting us to review it, and requesting for these changes to be merged into our main branch.
7279

7380
Here's how to effectively contribute via a PR:
7481

7582
- **Understand the Scope**: Before creating a PR, ensure it addresses an existing issue. Remember to link your PR to the issue it solves for easy tracking and understanding.
76-
- **Singular Focus**: Each PR should address a single issue or enhancement. Want to propose a larger change? Reach out to us on [Discord ](http://discord.com/invite/solidjs)and let's discuss the best way forward!
83+
- **Singular Focus**: Each PR should address a single issue or enhancement. Want to propose a larger change? Reach out to us on [Discord](http://discord.com/invite/solidjs) and let's discuss the best way forward!
7784
- **Drafts for Early Feedback**: If you're seeking early feedback but aren't quite finished with your changes, consider creating a draft PR. Simply prefix your PR title with `**[Draft]**`. This way, you can get input on your work-in-progress.
7885
- **Quality over Quantity**: Strive for the quality of your contribution rather than the quantity. A well-thought-out, cleanly coded, and thoroughly tested PR is much more valuable than a hastily done large one.
7986
Contributing via PRs not only enhances the project, but also allows you to be a part of the active community, sharing ideas, learning, and growing with the project.
@@ -83,16 +90,19 @@ Contributing via PRs not only enhances the project, but also allows you to be a
8390
### Writing a PR
8491
> Need help making a PR? [Join us on Discord](http://discord.com/invite/solidjs), we'll be more than happy to help you out!
8592
86-
Contributions to the documentation site are made by editing the docs repository. You can do this directly on GitHub.com or by creating a copy of the repository locally, making your changes there, and contributing back to our repository.
93+
Contributions to the documentation site are made by editing the docs repository.
94+
You can do this directly on GitHub.com or by creating a copy of the repository locally, making your changes there, and contributing back to our repository.
8795

8896
#### Examples of helpful PRs
8997
- PRs addressing an existing fix
90-
- unsolicited PRs addressing typos, broken links, and other minor problems
98+
- Unsolicited PRs addressing typos, broken links, and other minor problems
9199

92100
### Edit this page via GitHub
93-
Every page on [docs.solidjs.com ](https://docs.solidjs.com/)has an **Edit this page** link at the bottom. You can click on that button to edit the source code for that page in **GitHub**.
101+
Every page on [docs.solidjs.com](https://docs.solidjs.com/) has an **Edit this page** link at the bottom.
102+
You can click on that button to edit the source code for that page in **GitHub**.
94103

95-
After you make your changes, click **Commit changes**. This will automatically create a [fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks) of the docs in your GitHub account with the changes.
104+
After you make your changes, click **Commit changes**.
105+
This will automatically create a [fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks) of the docs in your GitHub account with the changes.
96106

97107
Once you have committed your edits within your fork, follow the prompts to create a **pull request** and submit your changes for review.
98108

@@ -101,11 +111,13 @@ Every pull request needs to be reviewed by our contributors and approved by a ma
101111
### Open a PR
102112
Once you have made your changes using your preferred method, you're ready to create a 'pull request'.
103113

104-
This will let the Solid docs team know you have some changes you would like to propose. At this point, we can give you feedback and possibly request changes.
114+
This will let the Solid docs team know you have some changes you would like to propose.
115+
At this point, we can give you feedback and possibly request changes.
105116

106117
[Read more about making a pull request in GitHub's docs.](https://docs.github.com/en/get-started/quickstart/contributing-to-projects#making-a-pull-request)
107118

108-
Please include a clear title. The description will have some pre-filled questions that we would like you to answer.
119+
Please include a clear title.
120+
The description will have some pre-filled questions that we would like you to answer.
109121

110122
Every pull request generates a preview of the site, including your proposed changes, using **Netlify** for anyone to see.
111123

@@ -115,15 +127,19 @@ The docs site will be automatically updated whenever pull requests are merged.
115127

116128
## Helpful information
117129
### Forks
118-
On GitHub, you will need a 'fork' of this repository to work on. This is your own copy of the code base where you can make changes. [You can read more about folks in GitHub's documentation.](https://guides.github.com/activities/forking/)
130+
On GitHub, you will need a 'fork' of this repository to work on.
131+
This is your own copy of the code base where you can make changes. You can read more about forks in [GitHub's documentation](https://guides.github.com/activities/forking/).
119132

120-
Not sure how to get started with GitHub, forks, pull requests, or want a refresher? You can watch this video series: [How to Contribute to an Open Source Project on GitHub](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github).
133+
Not sure how to get started with GitHub, forks, pull requests, or want a refresher?
134+
You can watch this video series: [How to Contribute to an Open Source Project on GitHub](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github).
121135

122136
#### Creating a fork
123137
To create your copy, click the `Fork` button at the top right of any page in this repository.
124138

125139
#### Maintaining a fork
126-
When you first create your fork, it will be an exact copy of this repository. Over time, our docs will change as they are updated, but your fork won’t automatically stay up-to-date. Here are some ways to keep your fork in sync with this repo:
140+
When you first create your fork, it will be an exact copy of this repository.
141+
Over time, our docs will change as they are updated, but your fork won’t automatically stay up-to-date.
142+
Here are some ways to keep your fork in sync with this repo:
127143

128144
##### Update through GitHub UI
129145
1. Navigate to your fork on GitHub

0 commit comments

Comments
 (0)