From c669ac4e86d8247cd529fd9fc4c55f592d4c45fe Mon Sep 17 00:00:00 2001 From: Jacob Herrington Date: Fri, 29 Nov 2019 12:51:38 -0600 Subject: [PATCH] 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. --- CONTRIBUTING.md | 135 +++++++++++++++++++++++++++++++++++++----------- 1 file changed, 106 insertions(+), 29 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0c7a029f1..99f9c4f4b 100644 --- a/CONTRIBUTING.md +++ b/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. ❤️