Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 93b5cca

Browse files
singingwolfboysingingwolfboy
committed
Merge pull request openedx#3503 from edx/db/process-updates
Reorganize information in CONTRIBUTING.rst, link to ReadTheDocs
2 parents f32e289 + 280bb96 commit 93b5cca

File tree

7 files changed

+264
-256
lines changed

7 files changed

+264
-256
lines changed

‎CONTRIBUTING.rst‎

Lines changed: 96 additions & 255 deletions
Large diffs are not rendered by default.

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ Contents:
2222
public_sandboxes.rst
2323
analytics.rst
2424
process/index
25+
testing/index
2526

2627
APIs
2728
-----

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

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ and effort making a pull request.
1818
It’s also sometimes useful to submit a pull request even before the code is
1919
working properly, to make it easier to collect early feedback. To indicate to
2020
others that your pull request is not yet in a functional state, just prefix the
21-
pull request title with "WIP:" (which stands for Work In Progress).
21+
pull request title with "(WIP)" (which stands for Work In Progress).
2222

2323
Once you’re ready to submit your changes in a pull request, check the following
2424
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
9595
try to suggest other ways that you can accomplish the same result in a way that
9696
we will accept.
9797

98+
Further Information
99+
-------------------
100+
For futher information on the pull request requirements, please see the following
101+
links:
102+
103+
* :doc:`../testing`
104+
* :doc:`../testing/jenkins`
105+
* :doc:`../testing/code-coverage`
106+
* :doc:`../testing/code-quality`
107+
* `Python Guidelines <https://github.com/edx/edx-platform/wiki/Python-Guidelines>`_
108+
* `Javascript Guidelines <https://github.com/edx/edx-platform/wiki/Javascript-Guidelines>`_
109+
98110
.. _contributor's agreement with edX: http://code.edx.org/individual-contributor-agreement.pdf
99111
.. _compatible licenses: https://github.com/edx/edx-platform/wiki/Licensing

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

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
*************
2+
Code Coverage
3+
*************
4+
5+
We measure which lines of our codebase are covered by unit tests using
6+
`coverage.py`_ for Python and `JSCover`_ for Javascript.
7+
8+
Our codebase is far from perfect, but the goal is to steadily improve our coverage
9+
over time. To do this, we wrote a tool called `diff-cover`_ that will
10+
report which lines in your branch are not covered by tests, while ignoring
11+
other lines in the project that may not be covered. Using this tool,
12+
we can ensure that pull requests have a very high percentage of test coverage
13+
-- and ideally, they increase the test coverage of existing code, as well.
14+
15+
To check the coverage of your pull request, just go to the top level of the
16+
edx-platform codebase and run::
17+
18+
$ rake coverage
19+
20+
This will print a coverage report for your branch. We aim for
21+
a coverage report score of 95% or higher. We also encourage you to write
22+
acceptance tests as your changes require.
23+
24+
.. _coverage.py: https://pypi.python.org/pypi/coverage
25+
.. _JSCover: http://tntim96.github.io/JSCover/
26+
.. _diff-cover: https://github.com/edx/diff-cover

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

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
************
2+
Code Quality
3+
************
4+
5+
In order to keep our code as clear and readable as possible, we use various
6+
tools to assess the quality of pull requests:
7+
8+
* We use the `pep8`_ tool to follow `PEP-8`_ guidelines
9+
* We use `pylint`_ for static analysis and uncovering trouble spots in our code
10+
11+
Our codebase is far from perfect, but the goal is to steadily improve our quality
12+
over time. To do this, we wrote a tool called `diff-quality`_ that will
13+
only report on the quality violations on lines that have changed in a
14+
pull request. Using this tool, we can ensure that pull requests do not introduce
15+
any new quality violations -- and ideally, they clean up existing violations
16+
in the process of introducing other changes.
17+
18+
To check the quality of your pull request, just go to the top level of the
19+
edx-platform codebase and run::
20+
21+
$ rake quality
22+
23+
This will print a report of the quality violations that your branch has made.
24+
25+
Although we try to be vigilant and resolve all quality violations, some Pylint
26+
violations are just too challenging to resolve, so we opt to ignore them via
27+
use of a pragma. A pragma tells Pylint to ignore the violation in the given
28+
line. An example is::
29+
30+
self.assertEquals(msg, form._errors['course_id'][0]) # pylint: disable=protected-access
31+
32+
The pragma starts with a ``#`` two spaces after the end of the line. We prefer
33+
that you use the full name of the error (``pylint: disable=unused-argument`` as
34+
opposed to ``pylint: disable=W0613``), so it's more clear what you're disabling
35+
in the line.
36+
37+
.. _PEP-8: http://legacy.python.org/dev/peps/pep-0008/
38+
.. _pep8: https://pypi.python.org/pypi/pep8
39+
.. _coverage.py: https://pypi.python.org/pypi/coverage
40+
.. _pylint: http://pylint.org/
41+
.. _diff-quality: https://github.com/edx/diff-cover

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

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
*******
2+
Testing
3+
*******
4+
5+
Testing is something that we take very seriously at edX: we even have a
6+
"test engineering" team at edX devoted purely to making our testing
7+
infrastructure even more awesome.
8+
9+
This file is currently a stub: to find out more about our testing infrastructure,
10+
check out the `testing.md`_ file on Github.
11+
12+
.. toctree::
13+
:maxdepth: 2
14+
15+
jenkins
16+
code-coverage
17+
code-quality
18+
19+
.. _testing.md: https://github.com/edx/edx-platform/blob/master/docs/en_us/internal/testing.md

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

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
*******
2+
Jenkins
3+
*******
4+
5+
`Jenkins`_ is an open source continuous integration server. edX has a Jenkins
6+
installation specifically for testing pull requests to our open source software
7+
project, including edx-platform. Before a pull request can be merged, Jenkins
8+
must run all the tests for that pull request: this is known as a "build".
9+
If even one test in the build fails, then the entire build is considered a
10+
failure. Pull requests cannot be merged until they have a passing build.
11+
12+
Kicking Off Builds
13+
==================
14+
15+
Jenkins has the ability to automatically detect new pull requests and changed
16+
pull requests on Github, and it can automatically run builds in response to
17+
these events. We have Jenkins configured to automatically run builds for all
18+
pull requests from core committers; however, Jenkins will *not* automatically
19+
run builds for new contributors, so a community manager will need to manually
20+
kick off a build for a pull request from a new contributor.
21+
22+
The reason for this distinction is a matter of trust. Running a build means that
23+
Jenkins will execute all the code in the pull request. A pull request can
24+
contain any code whatsoever: if we allowed Jenkins to automatically build every
25+
pull request, then a malicious developer could make our Jenkins server do whatever
26+
he or she wanted. Before kicking off a build, community managers look at the
27+
code changes to verify that they are not malicious; this protects us from nasty
28+
people.
29+
30+
Once a contributor has submitted a few pull requests, they can request to be
31+
added to the Jenkins whitelist: this is a special list of people that Jenkins
32+
*will* kick off builds for automatically. If the community managers feel that
33+
the contributor is trustworthy, then they will grant the request, which will
34+
make future development faster and easier for both the contributor and edX. If
35+
a contibutor shows that they can not be trusted for some reason, they will be
36+
removed from this whitelist.
37+
38+
Failed Builds
39+
=============
40+
41+
Click on the build to be brought to the build page. You'll see a matrix of blue
42+
and red dots; the red dots indicate what section failing tests were present in.
43+
You can click on the test name to be brought to an error trace that explains
44+
why the tests fail. Please address the failing tests before requesting a new
45+
build on your branch. If the failures appear to not have anything to do with
46+
your code, it may be the case that the master branch is failing. You can ask
47+
your reviewers for advice in this scenario.
48+
49+
If the build says "Unstable" but passes all tests, you have introduced too many
50+
pep8 and pylint violations. Please refer to the documentation for :doc:`code-quality`
51+
and clean up the code.
52+
53+
Successful Builds
54+
=================
55+
56+
If all the tests pass, the "Diff Coverage" and "Diff Quality" reports are
57+
generated. Click on the "View Reports" link on your pull request to be brought
58+
to the Jenkins report page. In a column on the left side of the page are a few
59+
links, including "Diff Coverage Report" and "Diff Quality Report". View each of
60+
these reports (making note that the Diff Quality report has two tabs - one for
61+
pep8, and one for Pylint).
62+
63+
Make sure your quality coverage is 100% and your test coverage is at least 95%.
64+
Adjust your code appropriately if these metrics are not high enough. Be sure to
65+
ask your reviewers for advice if you need it.
66+
67+
68+
.. _Jenkins: http://jenkins-ci.org/

0 commit comments

Comments
 (0)