We expect contributors to abide by our underlying 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 within 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.
All issues labeled ready for dev and type: bug all are up for grabs.
- good first issue are issues meant for newer developers.
While PRs without an associated ready for dev or type: bug labeled 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 by mentioning us on the issue.
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!
Refactoring code, or improving the code without modifying the behaviour, 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 behaviour. However, you might be asked to write a regression test if the area you've refactored isn't well covered. As refactoring can span many files it's always encouraged to proceed in steps if possible by submitting multiple smaller PRs.
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!
- Fork the project and clone it to your local machine. Follow the initial setup here.
- Create a branch with your GitHub username as a prefix and the ID of the
issue as a suffix, for
example:
git checkout -b USERNAME/that-new-feature-1234orgit checkout -b USERNAME/fixing-that-bug-1234whereUSERNAMEshould be replaced by your username and1234is the ID of the issue tied to your pull request. If there is no issue, you can leave the number out. - Code and commit your changes. Bonus points if you write a
good commit message:
git commit -m 'Add some feature'. - Push to the branch:
git push -u origin USERNAME/that-new-feature-1234. - Create a pull request for your branch. 🎉
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.
Some existing code may be poorly written or untested, so we must have more scrutiny going forward. We test with RSpec.
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 try to avoid wrong abstractions. Code quality tools are not perfect, so try not to obsess over your CodeClimate score.
Inclusion and respect are core tenents of our code of conduct and we encourage thoughtful language all the way down to the code. Some coding metaphors are alienating or triggering and we ask that contributors go the extra mile to submit code which is inclusive in nature.
If you unintentionally include language deemed harmful, there is no shame. We will simply work together to settle on an alternative we are all comfortable with. This extra care for naming tends to result in cleaner code as a byproduct.
- Try to keep the pull requests small. A pull request should try its very best to address only a single concern.
- If you plan to do further work after the PR is submitted, please use the Draft PR feature.
- Make sure all tests pass and add additional tests for the code you submit. More info here.
- 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. - 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 eventually 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.
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 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:
- it removes the review history of the code
- 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.
Please avoid force pushing unless you need to rebase with the master branch.
We are all humans trying to work together to improve the community. Always be kind and appreciate the need for tradeoffs. ❤️