Reorganize information in CONTRIBUTING.rst, link to ReadTheDocs

CONTRIBUTING.rst

@@ -2,26 +2,57 @@
 Contributing to edx-platform
 ############################
 
-Contributions to edx-platform are very welcome, and strongly encouraged! The
-easiest way is to fork the repo and then make a pull request from your fork.
-Check out our `process documentation`_, or read on for details on how to
-become a contributor, edx-platform code quality, testing, making a pull
-request, and more.
+Contributions to edx-platform are very welcome, and strongly encouraged! We've
+put together `some documentation that describes our contribution process`_,
+but here's a step-by-step guide that should help you get started.
 
-.. _process documentation: https://github.com/edx/edx-platform/blob/master/docs/en_us/developers/source/process/index.rst
+.. _some documentation that describes our contribution process: http://edx.readthedocs.org/projects/userdocs/en/latest/process/overview.html
 
-Becoming a Contributor
-======================
+Step 0: Join the Conversation
+=============================
 
-Before your first pull request is merged, you'll need to sign the `individual
-contributor agreement`_ and send it in. This confirms you have the authority to
-contribute the code in the pull request and ensures we can relicense it.
+Got an idea for how to improve the codebase? Fantastic; we'd love to hear about
+it! Before you dive in and spend a lot of time and effort making a pull request,
+it's a good idea to discuss your idea with other interested developers; you may
+get some valuable feedback that changes how you think about your idea, or you
+may find other developers who have the same idea and want to work together.
+
+For real-time conversation, we use `IRC`_: we all hang out in the
+`#edx-code channel on Freenode`_. Come join us! The channel tends to be most
+active Monday through Friday between 13:00 and 21:00 UTC
+(9am to 5pm US Eastern time), but interesting conversations can happen
+at any time.
+
+.. _IRC: http://www.irchelp.org/
+.. _#edx-code channel on Freenode: http://webchat.freenode.net/?channels=edx-code
+
+For asynchronous conversation, we have several mailing lists on Google Groups:
+
+* `openedx-ops`_: everything related to *running* Open edX. This includes
+  installation issues, server management, cost analysis, and so on.
+* `openedx-translation`_: everything related to *translating* Open edX into
+  other languages. This includes volunteer translators, our internationalization
+  infrastructure, issues related to Transifex, and so on.
+* `edx-code`_: everything related to the *code* in Open edX. This includes
+  feature requests, idea proposals, refactorings, and so on.
+
+.. _openedx-ops: https://groups.google.com/forum/#!forum/openedx-ops
+.. _openedx-translation: https://groups.google.com/forum/#!forum/openedx-translation
+.. _edx-code: https://groups.google.com/forum/#!forum/edx-code
+
+Step 1: Sign a Contribution Agreement
+=====================================
+
+Before edX can accept any code contributions from you, you'll need to sign
+the `individual contributor agreement`_ and send it in. This confirms
+that you have the authority to contribute the code in the pull request and
+ensures that edX can relicense it.
 
 You should print out the agreement and sign it. Then scan (or photograph) the
 signed agreement and email it to the email address indicated on the agreement.
 Alternatively, you're also free to physically mail the agreement to the street
 address on the agreement. Once we have your agreement in hand, we can begin
-merging your work.
+reviewing and merging your work.
 
 You'll also need to add yourself to the `AUTHORS` file when you submit your
 first pull request.  You should add your full name as well as the email address
@@ -31,156 +62,69 @@ request to contain multiple commits, including a commit to `AUTHORS`).
 Alternatively, you can open up a separate PR just to have your name added to
 the `AUTHORS` file, and link that PR to the PR with your changes.
 
+Step 2: Fork, Commit, and Pull Request
+======================================
+Github has some great documentation on `how to fork a git repository`_. Once
+you've done that, make your changes and `send us a pull request`_! Be sure to
+include a detailed description for your pull request, so that a community
+manager can understand *what* change you're making, *why* you're making it, *how*
+it should work now, and how you can *test* that it's working correctly.
 
-Code Quality Guidelines
-=======================
-
-Comments
---------
+.. _how to fork a git repository: https://help.github.com/articles/fork-a-repo
+.. _send us a pull request: https://help.github.com/articles/creating-a-pull-request
 
-We expect you to contribute code that is self-documenting as much as possible.
-This means submitting code with well-formed variable, function, class, and
-method names; good docstrings; lots of comments. Use your discretion - not
-every line needs to be commented. However, code that is obtuse is hard to
-maintain and hard for others to build upon. So please do your best to provide
-code that is easy to read and well-commented.
+Step 3: Meet PR Requirements
+============================
 
-Python/Javascript Styling
--------------------------
+Our `contributor documentation`_ includes a long list of requirements that pull
+requests must meet in order to be reviewed by a core committer. These requirements
+include things like documentation and passing tests: see the
+`contributor documentation`_ page for the full list.
 
-Before you submit your first pull request, please review the edx-platform code
-quality and style guidelines:
+.. _contributor documentation: http://edx.readthedocs.org/projects/userdocs/en/latest/process/contributor.html
 
-* `Python Guidelines <https://github.com/edx/edx-platform/wiki/Python-Guidelines>`_
-* `Javascript Guidelines <https://github.com/edx/edx-platform/wiki/Javascript-Guidelines>`_
+Step 4: Approval by Community Manager and Product Owner
+=======================================================
 
-Coding conventions should be followed. Your submission should not introduce any
-new pep8 or pylint errors (and ideally, should fix up other errors you
-encounter in the files you edit). From the edx-platform main directory, you can
-run the command::
+A community manager will read the description of your pull request. If the
+description is understandable, the community manager will send the pull request
+to a product owner. The product owner will evaluate if the pull request is a
+good idea for Open edX, and if not, your pull request will be rejected. This
+is another good reason why you should discuss your ideas with other members
+of the community before working on a pull request!
 
-    $ rake quality
+Step 5: Code Review by Core Committer(s)
+========================================
 
-to print the "Diff Quality" report, a report of the quality violations your
-branch has made.
+If your pull request meets the requirements listed in the
+`contributor documentation`_, and it hasn't been rejected by a product owner,
+then it will be scheduled for code review by one or more core committers. This
+process sometimes takes awhile: currently, all core committers on the project
+are employees of edX, and they have to balance their time between code review
+and new development.
 
-Although we try to be vigilant and resolve all quality violations, some Pylint
-violations are just too challenging to resolve, so we opt to ignore them via
-use of a pragma. A pragma tells Pylint to ignore the violation in the given
-line. An example is::
+Once the code review process has started, please be responsive to comments on
+the pull request, so we can keep the review process moving forward.
+If you are unable to respond for a few days, that's fine, but
+please add a comment informing us of that -- otherwise, it looks like you're
+abandoning your work!
 
-    self.assertEquals(msg, form._errors['course_id'][0])  # pylint: disable=protected-access
+Step 6: Merge!
+==============
 
-The pragma starts with a ``#`` two spaces after the end of the line. We prefer
-that you use the full name of the error (``pylint: disable=unused-argument`` as
-opposed to ``pylint: disable=W0613``), so it's more clear what you're disabling
-in the line.
+Once the core committers are satisfied that your pull request is ready to go,
+one of them will merge it for you. Your code will end up on the edX production
+servers in the next release, which usually which happens every week. Congrats!
 
-If you have any questions, don't hesitate to reach out to us on email or IRC;
-see the section on **Contacting Us**, below, for more.
 
-
-Testing Coverage Guidelines
 ===========================
-
-Before you submit a pull request, please refer to the `edx-platform testing
-documentation`_.
-
-Code you commit should *increase* test coverage, not decrease it. For more
-involved contributions, you may want to discuss your intentions on the mailing
-list *before* you start coding.
-
-Running the command ::
-
-    $ rake test
-
-in the edx-platform directory will run all the unit tests on edx-platform (to
-run specific tests, refer to the testing documentation). Once you've run this
-command, you can run ::
-
-    $ rake coverage
-
-to generate the "Diff Coverage" report. This report tells you how much of the
-Python and JavaScript code you've changed is covered by unit tests. We aim for
-a coverage report score of 95% or higher. We also encourage you to write
-acceptance tests as your changes require. For more in-depth help on various
-types of tests, please refer to the `edx-platform testing documentation`_.
-
-
-Opening A Pull Request
-======================
-
-When you open a pull request (PR), please follow these guidelines:
-
-* In the PR description, please be as clear as possible explaining what the
-  change is. This helps us so much in contextualizing your PR and providing
-  appropriate reviewers for you. Take a look at `pull request 1322`_ for an
-  example of a verbose PR description for a new feature.
-
-* As far as code goes, a first pass is to make sure that your code is of high
-  quality. This means ensuring plenty of comments, as well as a 100% pass rate
-  when you run ``rake quality`` locally. See the section **Code Quality
-  Guidelines**.
-
-* Testing coverage should be as complete as possible. 95% or greater on
-  JavaScript and Python coverage (you can check this by running ``rake test;
-  rake coverage`` locally). Percentage coverage is only calculated from unit
-  tests, however. If you're adding new visual features, we love seeing
-  acceptance tests as applicable. See the section **Testing Coverage
-  Guidelines**.
-
-* Be sure that your commit history is *clean* - that is, you don't have a ton
-  of tiny commits with throwaway commit messages such as "Fix", "Arugh",
-  "asdfjkl;", "Merge branch Master into fork", etc. Commit messages should be
-  concise and explain what work was done. The first line should be fewer than
-  50 characters; you may add additional lines to your commit messages for
-  further explaination.
-
-  * To clean up your commit history you'll need to perform an *interactive
-    rebase* where you squash your commits together. More about interactive
-    rebase can be found in the `github help documents`_ or by Googling.
-
-  * The reasoning behind a clean commit history is that we want the log of all
-    commits in edx-platform to be readable and self-documenting. This way,
-    developers can take a look at all recent commits in the past few days or
-    weeks and have a good understanding of all the code changes that were made.
-
-* The `CHANGELOG` is a list of changes to the platform, distinct from the git
-  log because the audience is not developers but rather users of our platform
-  (specifically, course authors). Please make an entry in `CHANGELOG`
-  describing your change if it is something that you think platform users would
-  be interested in - eg a major bugfix, new feature, or update to existing
-  functionality. Be sure to also indicate what system (LMS, CMS, etc) your
-  change affects. If in doubt if your change is "big enough", we encourage you
-  to make a `CHANGELOG` entry!
-
-* Make sure that your branch is freshly rebased on master when you go to open
-  your pull request. If you don't have repo permissions, you won't be able to
-  see if your branch is able to be cleanly merged or not. We'll tell you if
-  it's not; however, rebasing before you open your PR will help decrease the
-  frequency of conflicts.
-
-* If you need help with rebasing, please see the following resources:
-
-  1. `Git Book <http://git-scm.com/book/en/Git-Branching-Rebasing>`_
-  2. `Git Docs <http://git-scm.com/docs/git-rebase>`_
-  3. `Interactive Git tutorial <http://pcottle.github.io/learnGitBranching/>`_ -- totally awesome!!
-  4. `Git Ready <http://gitready.com/intermediate/2009/01/31/intro-to-rebase.html>`_
-
-
-Finally, **Please Do Not** close a pull request and open a new one to respond
-to review comments. Keep the same pull request open, so it's clear how your
-code has been worked upon and what reviewers have been involved in the
-conversation. Rebase as needed to get updated code from master into your
-branch.
-
-
 Expectations We Have of You
----------------------------
+===========================
 
 By opening up a pull request, we expect the following things:
 
-1. You've read and understand the instructions in this contributing file.
+1. You've read and understand the instructions in this contributing file and
+   the contribution process documentation.
 
 2. You are ready to engage with the edX community. Engaging means you will be
    prompt in following up with review comments and critiques. Do not open up a
@@ -193,124 +137,21 @@ By opening up a pull request, we expect the following things:
 4. If you do not respond to comments on your pull request within 7 days, we
    will close it. You are welcome to re-open it when you are ready to engage.
 
-
+=========================
 Expections You Have of Us
--------------------------
+=========================
 
-1. Within a week of opening up a pull request, one of our open source community
-   managers will triage it, either tagging other reviewers for the PR or asking
-   follow up questions (Please give us a little extra time if you open the PR
-   on a weekend or around a US holiday! We may take a little longer getting to
-   it.).
+1. Within a week of opening up a pull request, one of our community managers
+   will triage it, starting the documented contribution process. (Please
+   give us a little extra time if you open the PR on a weekend or
+   around a US holiday! We may take a little longer getting to it.)
 
 2. We promise to engage in an active dialogue with you from the time we begin
-   reviewing until either the PR is merged (by an edX staff member), or we
+   reviewing until either the PR is merged (by a core committer), or we
    decide that, for whatever reason, it should be closed.
 
 3. Once we have determined through visual review that your code is not
    malicious, we will run a Jenkins build on your branch.
 
-
-Using Jenkins Builds
---------------------
-
-When you open up a pull request, an edX staff member can decide to run a
-Jenkins build on your branch. We will do this once we have determined that your
-code is not malicious.
-
-When a Jenkins job is run, all unit, Javascript, and acceptance tests are run.
-
-**If the build fails...**
-
-Click on the build to be brought to the build page. You'll see a matrix of blue
-and red dots; the red dots indicate what section failing tests were present in.
-You can click on the test name to be brought to an error trace that explains
-why the tests fail. Please address the failing tests before requesting a new
-build on your branch. If the failures appear to not have anything to do with
-your code, it may be the case that the master branch is failing. You can ask
-your reviewers for advice in this scenario.
-
-If the build says "Unstable" but passes all tests, you have introduced too many
-pep8 and pylint violations. Please refer to the **Code Quality Guidelines**
-section and clean up the code.
-
-**If the build passes...**
-
-If all the tests pass, the "Diff Coverage" and "Diff Quality" reports are
-generated. Click on the "View Reports" link on your pull request to be brought
-to the Jenkins report page. In a column on the left side of the page are a few
-links, including "Diff Coverage Report" and "Diff Quality Report". View each of
-these reports (making note that the Diff Quality report has two tabs - one for
-pep8, and one for Pylint).
-
-Make sure your quality coverage is 100% and your test coverage is at least 95%.
-Adjust your code appropriately if these metrics are not high enough. Be sure to
-ask your reviewers for advice if you need it.
-
-
-Contacting Us
-=============
-
-Mailing list
-------------
-
-If you have any questions, please ask on the `mailing list`_. It's always a
-good idea to first search through the archives, to see if any of your questions
-have already been asked and answered.
-
-The edx platform team is based in the US, so we're best able to respond to
-questions posted in English. You're most likely to get an answer if you ask
-questions related to edx-platform code or conventions. Questions only
-tangentially related to edx-platform may be better answered on different forums
-or mailing lists (for example, asking for help on how to set up Git is better
-posted on a Git related message list or forum).
-
-Questions about translations, creating courses, or using Studio are not
-appropriate for the edx-code mailing list. We have a few other mailing lists
-you may be interested in:
-
-* `openedx-translation <https://groups.google.com/forum/#!forum/openedx-translation>`_
-* `openedx-studio <https://groups.google.com/forum/#!forum/openedx-studio>`_
-
-
-IRC
----
-
-Many edX employees and community members hang out in the #edx-code `IRC
-channel`_ on Freenode.  We're always happy to see more people hanging out with
-us there!
-
-**Tips on Using IRC**
-
-For clients, the `webchat <http://webchat.freenode.net>`_ is easiest, because you
-don't need to install anything and it's cross-platform.  `ChatZilla
-<http://chatzilla.hacksrus.com/>`_ is almost as easy -- it's a Firefox
-extension, and works anywhere Firefox does. For an installed application,
-`Pidgin <http://pidgin.im>`_ works decently (or `Adium <https://adium.im>`_ on
-Mac), and has a familiar instant-messenger-style interface. For something truly
-dedicated to IRC, there's `mIRC <http://www.mirc.com>`_ for Windows (free),
-`LimeChat <http://limechat.net/mac/>`_ for Mac (free), or `Textual
-<http://www.codeux.com/textual/>`_ for Mac (paid). There are also many other
-clients out there, but those are some good recommendations for people
-relatively new to IRC.
-
-
-Pull requests/issues
---------------------
-
-We do not make much use of Github issues, so opening an issue on edx-platform
-is not the best way to reach us. However, when you've opened up a pull request,
-please please don't be shy about adding comments and having a robust
-conversation with your pull request reviewers.
-
-Your pull request is a good place to ask pointed questions about the code
-you've written, and we're very happy to have interaction with you through code,
-commits, and comments.
-
-
 .. _individual contributor agreement: http://code.edx.org/individual-contributor-agreement.pdf
-.. _edx-platform testing documentation: https://github.com/edx/edx-platform/blob/master/docs/en_us/internal/testing.md
-.. _mailing list: https://groups.google.com/forum/#!forum/edx-code
-.. _IRC channel: http://www.irchelp.org/irchelp/new2irc.html
-.. _pull request 1322: https://github.com/edx/edx-platform/pull/1322
-.. _github help documents: https://help.github.com/articles/interactive-rebase
+

docs/en_us/developers/source/index.rst

@@ -18,6 +18,7 @@ Contents:
     overview.rst
     extending_platform/index
     process/index
+    testing/index
 
 APIs
 -----

docs/en_us/developers/source/process/contributor.rst

@@ -18,7 +18,7 @@ and effort making a pull request.
 It’s also sometimes useful to submit a pull request even before the code is
 working properly, to make it easier to collect early feedback. To indicate to
 others that your pull request is not yet in a functional state, just prefix the
-pull request title with "WIP:" (which stands for Work In Progress).
+pull request title with "(WIP)" (which stands for Work In Progress).
 
 Once you’re ready to submit your changes in a pull request, check the following
 list of requirements to be sure that your pull request is ready to be reviewed:
@@ -95,5 +95,17 @@ if we do reject your pull request, we will explain why we aren’t taking it, an
 try to suggest other ways that you can accomplish the same result in a way that
 we will accept.
 
+Further Information
+-------------------
+For futher information on the pull request requirements, please see the following
+links:
+
+* :doc:`../testing`
+* :doc:`../testing/jenkins`
+* :doc:`../testing/code-coverage`
+* :doc:`../testing/code-quality`
+* `Python Guidelines <https://github.com/edx/edx-platform/wiki/Python-Guidelines>`_
+* `Javascript Guidelines <https://github.com/edx/edx-platform/wiki/Javascript-Guidelines>`_
+
 .. _contributor's agreement with edX: http://code.edx.org/individual-contributor-agreement.pdf
 .. _compatible licenses: https://github.com/edx/edx-platform/wiki/Licensing

docs/en_us/developers/source/testing/code-coverage.rst

+*************
+Code Coverage
+*************
+
+We measure which lines of our codebase are covered by unit tests using
+`coverage.py`_ for Python and `JSCover`_ for Javascript.
+
+Our codebase is far from perfect, but the goal is to slowly improve our coverage
+over time. To do this, we wrote a tool called `diff-cover`_ that will
+report which lines in your branch are not covered by tests, while ignoring
+other lines in the project that may not be covered. Using this tool,
+we can ensure that pull requests have a very high percentage of test coverage
+-- and ideally, they increase the test coverage of existing code, as well.
+
+To check the coverage of your pull request, just go to the top level of the
+edx-platform codebase and run::
+
+    $ rake coverage
+
+This will print a coverage report for your branch. We aim for
+a coverage report score of 95% or higher. We also encourage you to write
+acceptance tests as your changes require.
+
+.. _coverage.py: https://pypi.python.org/pypi/coverage
+.. _JSCover: http://tntim96.github.io/JSCover/
+.. _diff-cover: https://github.com/edx/diff-cover

docs/en_us/developers/source/testing/code-quality.rst

+************
+Code Quality
+************
+
+In order to keep our codebase as clear and readable as possible, we use various
+tools to assess the quality of pull requests:
+
+* We use the `pep8`_ tool to follow `PEP-8`_ guidelines
+* We use `pylint`_ for static analysis and uncovering trouble spots in our code
+
+Our codebase is far from perfect, but the goal is to slowly improve our quality
+over time. To do this, we wrote a tool called `diff-quality`_ that will
+only report on the quality violations on lines that have changed in a
+pull request. Using this tool, we can ensure that pull requests do not introduce
+any new quality violations -- and ideally, they clean up existing violations
+in the process of introducing other changes.
+
+To check the quality of your pull request, just go to the top level of the
+edx-platform codebase and run::
+
+    $ rake quality
+
+This will print a report of the quality violations that your branch has made.
+
+Although we try to be vigilant and resolve all quality violations, some Pylint
+violations are just too challenging to resolve, so we opt to ignore them via
+use of a pragma. A pragma tells Pylint to ignore the violation in the given
+line. An example is::
+
+    self.assertEquals(msg, form._errors['course_id'][0])  # pylint: disable=protected-access
+
+The pragma starts with a ``#`` two spaces after the end of the line. We prefer
+that you use the full name of the error (``pylint: disable=unused-argument`` as
+opposed to ``pylint: disable=W0613``), so it's more clear what you're disabling
+in the line.
+
+.. _PEP-8: http://legacy.python.org/dev/peps/pep-0008/
+.. _pep8: https://pypi.python.org/pypi/pep8
+.. _coverage.py: https://pypi.python.org/pypi/coverage
+.. _pylint: http://pylint.org/
+.. _diff-quality: https://github.com/edx/diff-cover

docs/en_us/developers/source/testing/index.rst

+*******
+Testing
+*******
+
+Testing is something that we take very seriously at edX: we even have a
+"test engineering" team at edX devoted purely to making our testing
+infrastructure even more awesome.
+
+This file is currently a stub: to find out more about our testing infrastructure,
+check out the `testing.md`_ file on Github.
+
+.. toctree::
+    :maxdepth: 2
+
+    jenkins
+    code-coverage
+    code-quality
+
+.. _testing.md: https://github.com/edx/edx-platform/blob/master/docs/en_us/internal/testing.md

docs/en_us/developers/source/testing/jenkins.rst

+*******
+Jenkins
+*******
+
+`Jenkins`_ is an open source continuous integration server. edX has a Jenkins
+installation specifically for testing pull requests to our open source software
+project, including edx-platform. Before a pull request can be merged, Jenkins
+must run all the tests for that pull request: this is known as a "build".
+If even one test in the build fails, then the entire build is considered a
+failure. Pull requests cannot be merged until they have a passing build.
+
+Kicking Off Builds
+==================
+
+Jenkins has the ability to automatically detect new pull requests and changed
+pull requests on Github, and it can automatically run builds in response to
+these events. We have Jenkins configured to automatically run builds for all
+pull requests from core committers; however, Jenkins will *not* automatically
+run builds for new contributors, so a community manager will need to manually
+kick off a build for a pull request from a new contributor.
+
+The reason for this distinction is a matter of trust. Running a build means that
+Jenkins will execute all the code in the pull request. A pull request can
+contain any code whatsoever: if we allowed Jenkins to automatically build every
+pull request, then a malicious developer could make our Jenkins server do whatever
+he or she wanted. Before kicking off a build, community managers look at the
+code changes to verify that they are not malicious; this protects us from nasty
+people.
+
+Once a contributor has submitted a few pull requests, they can request to be
+added to the Jenkins whitelist: this is a special list of people that Jenkins
+*will* kick off builds for automatically. If the community managers feel that
+the contributor is trustworthy, then they will grant the request, which will
+make future development faster and easier for both the contributor and edX. If
+a contibutor shows that they can not be trusted for some reason, they will be
+removed from this whitelist.
+
+Failed Builds
+=============
+
+Click on the build to be brought to the build page. You'll see a matrix of blue
+and red dots; the red dots indicate what section failing tests were present in.
+You can click on the test name to be brought to an error trace that explains
+why the tests fail. Please address the failing tests before requesting a new
+build on your branch. If the failures appear to not have anything to do with
+your code, it may be the case that the master branch is failing. You can ask
+your reviewers for advice in this scenario.
+
+If the build says "Unstable" but passes all tests, you have introduced too many
+pep8 and pylint violations. Please refer to the documentation for :doc:`code-quality`
+and clean up the code.
+
+Successful Builds
+=================
+
+If all the tests pass, the "Diff Coverage" and "Diff Quality" reports are
+generated. Click on the "View Reports" link on your pull request to be brought
+to the Jenkins report page. In a column on the left side of the page are a few
+links, including "Diff Coverage Report" and "Diff Quality Report". View each of
+these reports (making note that the Diff Quality report has two tabs - one for
+pep8, and one for Pylint).
+
+Make sure your quality coverage is 100% and your test coverage is at least 95%.
+Adjust your code appropriately if these metrics are not high enough. Be sure to
+ask your reviewers for advice if you need it.
+
+
+.. _Jenkins: http://jenkins-ci.org/