From a2d319484a3c98dda388df609e9ddfbb6a4affa9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rog=C3=A9rio=20Brito?= Date: Thu, 30 Apr 2015 09:25:06 -0300 Subject: [PATCH] CONTRIBUTING: Be more detailed in how we prefer contributions. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit I have had to ask "why should we change from tool to " a few times now for the project and some of the commit messages seem like they could have already have answered all these questions beforehand. Signed-off-by: Rogério Brito --- CONTRIBUTING.md | 74 +++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 63 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index db537d8..7d6c618 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,21 +1,73 @@ -Please, before sending patches, it is helpful if you: +Please, before sending patches, read these brief comments. They are here to +help the project have both its users happy using the program and the +developers/maintainers feel good when trying to change code that other +people contributed. -* Make sure that you have all dependencies installed, like via +For the record, when this document mentions "I", it mostly means Rogério +Brito's (@rbrito) is the one to blame. - pip install -r requirements.txt - pip install -r requirements-dev.txt +# Write good commit messages -* Run the test suite with +When you write your pull request and your commit messages, please, be +detailed, explaining why you are doing what you are doing. Don't be afraid +of being too verbose here. Also, please follow the highly recommended +guidelines on how to write good [good commit messages][commit-msgs]. - py.test coursera/test -v --cov coursera --cov-report html +When in doubt, follow the model of the Linux kernel commit logs. Their +commit messages are some of the best that I have seen. Also, the ffmpeg has +some good messages that I believe that should be followed. If you are in a +hurry, read the section named +["Contributing" from subsurface's README][contributing]. -* Check for any potential bugs with the help of [`pep8`][pep8], - [`pyflakes`][pyflakes], and [`pylint`][pylint]. +[commit-msgs]: https://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message +[contributing]: https://github.com/torvalds/subsurface/blob/master/README#L71-L114 + + +# Test that your changes don't break existing functionality + +Make sure that you have all dependencies installed, like via: + + pip install -r requirements.txt + pip install -r requirements-dev.txt + +Run the test suite with + + py.test coursera/test -v --cov coursera --cov-report html + +If some test fails, please don't send your changes yet. Fix what broke +before sending your pull request. + +If you need to change the test suite, explain in the commit message why it +needs to be changed (e.g., the page layout or the authentication methods +from coursera changed, or they implemented a new kind of course). + +# Check for potential bugs + +Please, help keep the code tidy by checking for any potential bugs with the +help of [`pep8`][pep8], [`pyflakes`][pyflakes], and [`pylint`][pylint]. If +you know of any other good tools for analyzing the code, let me know about +them! [pep8]: https://pypi.python.org/pypi/pep8 [pyflakes]: https://pypi.python.org/pypi/pyflakes/ [pylint]: https://pypi.python.org/pypi/pylint -If you happen to find any issue reported by these programs, we would welcome -you to fix them, as they are usually very easy to fix and we would all -benefit from a better code base. +If you happen to find any issue reported by these programs, I welcome you to +fix them. Many of the issues are usually very easy to fix and they are a +great way to start contributing to this (and other projects in general). +Furthermore, we all benefit from a better code base. + +# Changes in the tools that we use + +If you are proposing the use of a substitute of a tool that we already use, +take a few paragraphs to tell us why we would like to change. + +If we are not using something, it is most likely that one of the following +options applies: + +1. I (@rbrito) may know even know that what you are proposing exists or have + not yet "seen the light" as to why I should use it instead of using what + I am currently using. +2. Even if I know about the tool, I may not know how to use it, or how it + would make me more productive. Educate me and we all will gain from a + better project.