зеркало из https://github.com/mozilla/kitsune.git
Docs updates
* Splits the docs into three sections---trying to reduce the "omg! there are a million sections!" overwhelming feeling * Moves the test-related things to the tests chapter so they're all in one place * Turned "coding" into "conventions"---that's what it really is. * Fleshed out the git commit message conventions---it keeps coming up and we pointed to a guide which pointed to a guide and the links were buried in both places.
This commit is contained in:
Will Kahn-Greene
Родитель
d7439340e8
Коммит
51697e0461
|
|
@ -1,43 +0,0 @@
|
|||
========================================
|
||||
Coding Conventions and Other Coding Info
|
||||
========================================
|
||||
|
||||
This document contains useful information about our coding conventions, and
|
||||
things to watch out for, etc.
|
||||
|
||||
|
||||
Coding conventions
|
||||
==================
|
||||
|
||||
We follow most of the practices as detailed in the `Mozilla webdev bootcamp
|
||||
guide <http://mozweb.readthedocs.org/en/latest/coding.html>`_.
|
||||
|
||||
|
||||
Git conventions
|
||||
===============
|
||||
|
||||
See :ref:`patching` for our Git usage conventions.
|
||||
|
||||
See `Webdev bootcamp guide
|
||||
<http://mozweb.readthedocs.org/en/latest/git.html#git-and-github>`_
|
||||
for:
|
||||
|
||||
* git commit message conventions
|
||||
* helpful resources for learning git
|
||||
* helpful tools
|
||||
|
||||
|
||||
Tests
|
||||
=====
|
||||
|
||||
* Avoid naming test files ``test_utils.py``, since we use a library with the
|
||||
same name. Use ``test__utils.py`` instead.
|
||||
|
||||
* If you're expecting ``reverse`` to return locales in the URL, use
|
||||
``LocalizingClient`` instead of the default client for the ``TestCase``
|
||||
class.
|
||||
|
||||
* Many models have "modelmakers" which are easier to work with for
|
||||
some kinds of tests than fixtures. For example,
|
||||
``forums.tests.document`` is the model maker for
|
||||
``forums.models.Document``.
|
||||
|
|
@ -26,11 +26,11 @@ the case that we're not around. Please try pinging us again.
|
|||
|
||||
Current primary developers:
|
||||
|
||||
.. comment::
|
||||
|
||||
This is a slight repeat from AUTHORS. We just need to point out
|
||||
people to contact if someone is having problems.
|
||||
.. This is a slight repeat from AUTHORS. We just need to point out
|
||||
.. people to contact if someone is having problems.
|
||||
|
||||
* James Socol (jsocol)
|
||||
* Ricky Rosario (r1cky)
|
||||
* Will Kahn-Greene (willkg)
|
||||
* Rehan Dalal (rdalal)
|
||||
* Mike Cooper (mythmon)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,69 @@
|
|||
===========
|
||||
Conventions
|
||||
===========
|
||||
|
||||
This document contains coding conventions, and things to watch out
|
||||
for, etc.
|
||||
|
||||
|
||||
Coding conventions
|
||||
==================
|
||||
|
||||
We follow most of the practices as detailed in the `Mozilla webdev
|
||||
bootcamp guide
|
||||
<http://mozweb.readthedocs.org/en/latest/coding.html>`_.
|
||||
|
||||
If you don't have an editor that checks PEP-8 issues and runs pyflakes
|
||||
for you, it's worth setting it up. Use `check.py
|
||||
<https://github.com/jbalogh/check>`_ because it's awesome.
|
||||
|
||||
|
||||
Git conventions
|
||||
===============
|
||||
|
||||
Git workflow
|
||||
------------
|
||||
|
||||
See :ref:`patching` for how we use Git, branches and merging.
|
||||
|
||||
|
||||
Git commit messages
|
||||
-------------------
|
||||
|
||||
Git commit messages should have the following form::
|
||||
|
||||
[bug xxxxxxx] Short summary
|
||||
|
||||
Longer explanation with paragraphs and lists and all that where
|
||||
each line is under 72 characters.
|
||||
|
||||
* bullet 1
|
||||
* bullet 2
|
||||
|
||||
Etc. etc.
|
||||
|
||||
|
||||
Summary line should be capitalized, short and shouldn't exceed 50
|
||||
characters. Why? Because this is a convention many git tools take
|
||||
advantage of.
|
||||
|
||||
If the commit relates to a bug, the bug should show up in the summary
|
||||
line in brackets.
|
||||
|
||||
There should be a blank line between the summary and the rest of the
|
||||
commit message. Lines shouldn't exceed 72 characters.
|
||||
|
||||
See `these guidelines
|
||||
<http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html>`_
|
||||
for some more explanation.
|
||||
|
||||
|
||||
Git resources and tools
|
||||
-----------------------
|
||||
|
||||
See `Webdev bootcamp guide
|
||||
<http://mozweb.readthedocs.org/en/latest/git.html#git-and-github>`_
|
||||
for:
|
||||
|
||||
* helpful resources for learning git
|
||||
* helpful tools
|
||||
|
|
@ -1,12 +1,9 @@
|
|||
.. Kitsune documentation master file, created by
|
||||
sphinx-quickstart on Sat Sep 10 11:40:02 2011.
|
||||
You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
===================================
|
||||
Welcome to Kitsune's documentation!
|
||||
===================================
|
||||
|
||||
Contents helpful for contributors:
|
||||
Part 1: Contributor's Guide
|
||||
===========================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
|
@ -16,27 +13,36 @@ Contents helpful for contributors:
|
|||
contactus
|
||||
|
||||
|
||||
Contents helpful for developers:
|
||||
Part 2: Developer's Guide
|
||||
=========================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
installation
|
||||
coding
|
||||
conventions
|
||||
patching
|
||||
development
|
||||
bots
|
||||
tests
|
||||
celery
|
||||
deployments
|
||||
wsgi
|
||||
email
|
||||
localization
|
||||
licenses
|
||||
searchchapter
|
||||
armyofawesome
|
||||
tests
|
||||
vendor
|
||||
wikidocs
|
||||
licenses
|
||||
|
||||
|
||||
Part 3: SUMO
|
||||
============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
bots
|
||||
deployments
|
||||
sla
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,12 +1,12 @@
|
|||
.. _tests-chapter:
|
||||
|
||||
======================
|
||||
The Kitsune Test Suite
|
||||
======================
|
||||
=================
|
||||
All about testing
|
||||
=================
|
||||
|
||||
Kitsune has a fairly comprehensive Python test suite. Changes should not break
|
||||
tests--only change a test if there is a good reason to change the expected
|
||||
behavior--and new code should come with tests.
|
||||
tests---only change a test if there is a good reason to change the expected
|
||||
behavior---and new code should come with tests.
|
||||
|
||||
|
||||
Running the Test Suite
|
||||
|
|
@ -39,14 +39,22 @@ Some other helpful flags are:
|
|||
assertion.
|
||||
|
||||
|
||||
Running a Subset
|
||||
----------------
|
||||
Running a Subset of Tests
|
||||
-------------------------
|
||||
|
||||
You can run part of the test suite by specifying the apps you want to run,
|
||||
like::
|
||||
|
||||
./manage.py test wiki search kbforums
|
||||
|
||||
You can also specify modules::
|
||||
|
||||
./manage.py test wiki.tests.test_views
|
||||
|
||||
You can specify specific tests::
|
||||
|
||||
./manage.py test wiki.tests.test_views:VersionGroupTests.test_version_groups
|
||||
|
||||
You can also exclude tests that match a regular expression with ``-e``::
|
||||
|
||||
./manage.py test -e"search"
|
||||
|
|
@ -58,8 +66,10 @@ The Test Database
|
|||
-----------------
|
||||
|
||||
The test suite will create a new database named ``test_%s`` where ``%s`` is
|
||||
whatever value you have for ``settings.DATABASES['default']['NAME']``. Make
|
||||
sure the user has ``ALL`` on the test database as well.
|
||||
whatever value you have for ``settings.DATABASES['default']['NAME']``.
|
||||
|
||||
Make sure the user has ``ALL`` on the test database as well. This is
|
||||
covered in the installation chapter.
|
||||
|
||||
When the schema changes, you may need to drop the test database. You can also
|
||||
run the test suite with ``FORCE_DB`` once to cause Django to drop and recreate
|
||||
|
|
@ -68,8 +78,8 @@ it::
|
|||
FORCE_DB=1 ./manage.py test -s --noinput --logging-clear-handlers
|
||||
|
||||
|
||||
Adding Tests
|
||||
============
|
||||
Writing New Tests
|
||||
=================
|
||||
|
||||
Code should be written so it can be tested, and then there should be tests for
|
||||
it.
|
||||
|
|
@ -79,6 +89,18 @@ new functionality. All apps have a ``tests`` module where tests should go. They
|
|||
will be discovered automatically by the test runner as long as the look like a
|
||||
test.
|
||||
|
||||
* Avoid naming test files ``test_utils.py``, since we use a library
|
||||
with the same name. Use ``test__utils.py`` instead.
|
||||
|
||||
* If you're expecting ``reverse`` to return locales in the URL, use
|
||||
``LocalizingClient`` instead of the default client for the
|
||||
``TestCase`` class.
|
||||
|
||||
* Many models have "modelmakers" which are easier to work with for
|
||||
some kinds of tests than fixtures. For example,
|
||||
``forums.tests.document`` is the model maker for
|
||||
``forums.models.Document``.
|
||||
|
||||
|
||||
Changing Tests
|
||||
==============
|
||||
|
|
@ -104,6 +126,7 @@ JavaScript Tests
|
|||
Frontend JavaScript is currently tested with QUnit_, a simple set of
|
||||
functions for test setup/teardown and assertions.
|
||||
|
||||
|
||||
Running JavaScript Tests
|
||||
------------------------
|
||||
|
||||
|
|
@ -119,6 +142,7 @@ file so it includes django-qunit::
|
|||
'django_qunit',
|
||||
)
|
||||
|
||||
|
||||
Writing JavaScript Tests
|
||||
------------------------
|
||||
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче