Expand the contributing guide (#4947)
* Add 80 character linewrap * Expand the contributing guide [ci skip] This commit includes a couple of expansions on the contributing guide including some notes concerning documentation and the code of conduct. There are also some small mechanical fixes and a link or two was fixed.
This commit is contained in:
Jacob Herrington
Ben Halpern
parent
cfd5434d6c
commit
c669ac4e86
1 changed files with 106 additions and 29 deletions
135
CONTRIBUTING.md
135
CONTRIBUTING.md
|
|
@ -12,71 +12,148 @@
|
|||
|
||||
## Contributing
|
||||
|
||||
We expect contributors to abide by our underlying [code of conduct](https://dev.to/code-of-conduct). All conversations and discussions on GitHub (issues, pull requests) and across dev.to must be respectful and harassment-free.
|
||||
We expect contributors to abide by our underlying
|
||||
[code of conduct](https://dev.to/code-of-conduct). All conversations and
|
||||
discussions on GitHub (issues, pull requests) and across dev.to must be
|
||||
respectful and harassment-free.
|
||||
|
||||
Remember that communication is the lifeblood of any Open Source project. We are
|
||||
all working on this together, and we are all benefiting from this software. It's
|
||||
very easy to misunderstand one another over asynchronous, text-based
|
||||
conversations: When in doubt, assume everyone you're interacting with in this
|
||||
project has the best intentions.
|
||||
|
||||
If you feel another member of the community has violated our Code of Conduct,
|
||||
you may anonymously contact the team with our
|
||||
[abuse report form](https://dev.to/report-abuse).
|
||||
|
||||
### Where to contribute
|
||||
|
||||
All [issues](https://github.com/thepracticaldev/dev.to/issues) labeled with `help wanted` are up for grabs.
|
||||
All [issues](https://github.com/thepracticaldev/dev.to/issues) labeled with
|
||||
`help wanted` are up for grabs.
|
||||
|
||||
- `good first issue` are issues meant for newer developers.
|
||||
- `type: discussion` are issues we haven't decided to move forward with, or need more information before proceeding.
|
||||
- `type: discussion` are issues we haven't decided to move forward with, or need
|
||||
more information before proceeding.
|
||||
|
||||
While PRs without an associated `help wanted` issue may still be merged, please note that the core team will prioritize PRs that solve existing issues first. We strongly encourage creating an issue before working on a PR!
|
||||
While PRs without an associated `help wanted` issue may still be merged, please
|
||||
note that the core team will prioritize PRs that solve existing issues. We
|
||||
strongly encourage creating an issue before working on a PR!
|
||||
|
||||
When in doubt, ask a [core team member](https://github.com/thepracticaldev/dev.to/#core-team) by mentioning us on the issue.
|
||||
When in doubt, ask a
|
||||
[core team member](https://github.com/thepracticaldev/dev.to/#core-team) by
|
||||
mentioning us on the issue.
|
||||
|
||||
**Refactoring** code, e.g., improving the code without modifying the behavior is an area that can probably be done based on intuition and may not require much communication to be merged.
|
||||
**Documentation** is almost always a great place to start contributing to a new
|
||||
project. DEV is an Open Source, community-driven project, so providing and
|
||||
maintaining quality documentation is one of our most important jobs. You can
|
||||
find more information about contributing to the documentation in the
|
||||
[docs/ directory](https://github.com/thepracticaldev/dev.to/blob/master/docs/contributing.md)!
|
||||
|
||||
**Fixing bugs** may also not require a lot of communication, but the more, the better. Please surround bug fixes with ample tests. Bugs are magnets for other bugs. Write tests around bugs!
|
||||
**Refactoring** code, or improving the code without modifying the behavior, is
|
||||
an area that can probably be done based on intuition and may not require much
|
||||
communication to be merged. Generally speaking, you can rely on existing tests
|
||||
to ensure that your refactoring doesn't introduce any unexpected behavior.
|
||||
However, you might be asked to write a regression test if the area you've
|
||||
refactored isn't well covered.
|
||||
|
||||
**Building features** is the area which will require the most communication and/or negotiation. Every feature is subjective and open for debate. If your feature involves user-facing design changes, please provide a mockup first so we can all get on the same page. As always, when in doubt, ask!
|
||||
**Fixing bugs** may also not require a lot of communication, but it's always
|
||||
better to let us know what you're working on! Please surround bug fixes with
|
||||
ample tests; bugs are magnets for other bugs. Write tests around bugs!
|
||||
|
||||
**Building features** is the area that will require the most communication
|
||||
and/or negotiation. Every feature is subjective and open for debate. If your
|
||||
feature involves user-facing design changes, please provide a mockup first so we
|
||||
can all get on the same page. As always, when in doubt, ask!
|
||||
|
||||
### How to contribute
|
||||
|
||||
1. Fork the project and clone it to your local machine. Follow the initial setup [here](https://github.com/thepracticaldev/dev.to/#getting-started).
|
||||
2. Create a branch with your GitHub username as a prefix and the ID of the [issue](https://github.com/thepracticaldev/dev.to/issues) as a suffix, for example: `git checkout -b USERNAME/that-new-feature-1234` or `git checkout -b USERNAME/fixing-that-bug-1234` where `USERNAME` should be replaced by your username and `1234` is the ID of the issue tied to your pull request. If there is no issue, you can leave the number out.
|
||||
3. Code and commit your changes. Bonus points if you write a [good commit message](https://chris.beams.io/posts/git-commit/): `git commit -m 'Add some feature'`
|
||||
1. [Fork the project](https://docs.dev.to/getting-started/forking/) and clone it
|
||||
to your local machine. Follow the initial setup
|
||||
[here](https://docs.dev.to/installation/).
|
||||
2. Create a branch with your GitHub username as a prefix and the ID of the
|
||||
[issue](https://github.com/thepracticaldev/dev.to/issues) as a suffix, for
|
||||
example: `git checkout -b USERNAME/that-new-feature-1234` or
|
||||
`git checkout -b USERNAME/fixing-that-bug-1234` where `USERNAME` should be
|
||||
replaced by your username and `1234` is the ID of the issue tied to your pull
|
||||
request. If there is no issue, you can leave the number out.
|
||||
3. Code and commit your changes. Bonus points if you write a
|
||||
[good commit message](https://chris.beams.io/posts/git-commit/):
|
||||
`git commit -m 'Add some feature'`
|
||||
4. Push to the branch: `git push origin USERNAME/that-new-feature-1234`
|
||||
5. [Create a pull request](https://docs.dev.to/getting-started/pull-request/) for your branch 🎉
|
||||
5. [Create a pull request](https://docs.dev.to/getting-started/pull-request/)
|
||||
for your branch 🎉
|
||||
|
||||
## Contribution guidelines
|
||||
|
||||
### Create an issue
|
||||
|
||||
Nobody's perfect. Something doesn't work? Something could be done better? Check to see if the issue already exists and if it does, leave a comment to get our attention! And if the issue doesn't already exist, feel free to create a new one. A core team member will triage incoming issues.
|
||||
Nobody's perfect. Something doesn't work? Something could be done better? Check
|
||||
to see if the issue already exists, and if it does, leave a comment to get our
|
||||
attention! If the issue doesn't already exist, feel free to create a new one. A
|
||||
core team member will triage incoming issues.
|
||||
|
||||
_Please note: core team members may update the title of an issue to more accurately reflect the request/bug._
|
||||
_Please note: core team members may update the title of an issue to more
|
||||
accurately reflect the request/bug._
|
||||
|
||||
### Clean code with tests
|
||||
### Please include tests
|
||||
|
||||
Some existing code may be poorly written or untested, so we must have more scrutiny going forward. We test with [rspec](http://rspec.info/).
|
||||
Some existing code may be poorly written or untested, so we must have more
|
||||
scrutiny going forward. We test with [rspec](http://rspec.info/).
|
||||
|
||||
### Code quality
|
||||
|
||||
We use CodeClimate to evaluate code smells. If a pull request contributes a
|
||||
significant number of code smells, you may be asked to refactor your change
|
||||
before it is merged. Focusing on writing reasonably DRY code with a focus on
|
||||
readability will help avoid unnecessary code smells.
|
||||
|
||||
More importantly, we also avoid
|
||||
[the wrong abstractions](https://www.sandimetz.com/blog/2016/1/20/the-wrong-abstraction).
|
||||
Code quality tools are not perfect, so try not to obsess over your CodeClimate
|
||||
score.
|
||||
|
||||
### Create a pull request
|
||||
|
||||
- Try to keep the pull requests small. A pull request should try its very best to address only a single concern.
|
||||
- Make sure all tests pass and add additional tests for the code you submit. [More info here](https://docs.dev.to/tests/).
|
||||
- Document your reasoning behind the changes. Explain why you wrote the code in the way you did. The code should explain what it does.
|
||||
- If there's an existing issue related to the pull request, reference to it by adding something like `References/Closes/Fixes/Resolves #305`, where 305 is the issue number. [More info here](https://github.com/blog/1506-closing-issues-via-pull-requests).
|
||||
- Try to keep the pull requests small. A pull request should try its very best
|
||||
to address only a single concern.
|
||||
- Make sure all tests pass and add additional tests for the code you submit.
|
||||
[More info here](https://docs.dev.to/tests/).
|
||||
- Document your reasoning behind the changes. Explain why you wrote the code in
|
||||
the way you did. The code should explain what it does.
|
||||
- If there's an existing issue related to the pull request, reference to it by
|
||||
adding something like `References/Closes/Fixes/Resolves #305`, where 305 is
|
||||
the issue number.
|
||||
[More info here](https://github.com/blog/1506-closing-issues-via-pull-requests).
|
||||
- Please fill out the PR Template when making a PR.
|
||||
- All commits in a pull request will be squashed when merged, but when your PR is approved and passes our CI, it will be live on production!
|
||||
- All commits in a pull request will be squashed when merged, but when your PR
|
||||
is approved and passes our CI, it will be live on production!
|
||||
|
||||
_Please note: a core team member may close your PR if it has gone stale or if we don't plan to merge the code._
|
||||
_Please note: a core team member may close your PR if it has gone stale or if we
|
||||
don't plan to merge the code._
|
||||
|
||||
### Pull requests reviews and "force pushing"
|
||||
|
||||
After you submit your pull request (PR), one of the members of the core team or core contributors will likely do a review of the code accepting it or giving feedback.
|
||||
After you submit your pull request (PR), one of the members of the core team or
|
||||
core contributors will likely do a review of the code accepting it or giving
|
||||
feedback.
|
||||
|
||||
If feedback or suggestions are provided, any following modifications on your part should happen in separate commits added to the existing ones.
|
||||
If feedback or suggestions are provided, any changes on your part should happen
|
||||
in separate commits added to the existing ones.
|
||||
|
||||
Force pushing, though understandable for reasons of wanting to keep the history clean, has some drawbacks:
|
||||
Force pushing, though understandable for reasons of wanting to keep the history
|
||||
clean, has some drawbacks:
|
||||
|
||||
- it removes the review history of the code
|
||||
- forces the reviewer to start from scratch when adding possible further comments
|
||||
- forces the reviewer to start from scratch when adding possible further
|
||||
comments
|
||||
|
||||
PRs will be squashed and merged into master, so there's no need to use force push.
|
||||
PRs will be squashed and merged into master, so there's no need to use force
|
||||
push.
|
||||
|
||||
Please avoid force pushing unless you are in need to do a rebase from master.
|
||||
Please avoid force pushing unless you need to rebase with master.
|
||||
|
||||
## The bottom line
|
||||
|
||||
We are all humans trying to work together to improve the community. Always be kind and appreciate the need for tradeoffs. ❤️
|
||||
We are all humans trying to work together to improve the community. Always be
|
||||
kind and appreciate the need for tradeoffs. ❤️
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue