~rashi007/mailman/docsfix

« back to all changes in this revision

Viewing changes to src/mailman/docs/START.rst

  • Committer: Barry Warsaw
  • Date: 2014-11-08 15:27:56 UTC
  • mfrom: (7255 3.0)
  • mto: This revision was merged to the branch mainline in revision 7260.
  • Revision ID: barry@list.org-20141108152756-p37fhmb0z2dtl7hx
Trunk merge.

Show diffs side-by-side

added added

removed removed

Lines of Context:
65
65
how to set up a complete Mailman 3 system including the Mailman 3 core
66
66
and basic client API, Postorius, and HyperKitty.
67
67
 
68
 
Building Mailman 3
69
 
==================
70
 
 
71
 
To build Mailman for development purposes, you will create a virtual
72
 
environment.  You need to have the `virtualenv`_ program installed.
 
68
Testing Mailman 3
 
69
=================
 
70
 
 
71
To run the Mailman test suite, just use the `tox`_ command.  `tox` creates a
 
72
virtual environment (virtualenv) for you, installs all the dependencies into
 
73
that virtualenv, and runs the test suite from that virtualenv.  By default it
 
74
does not use the `--system-site-packages` so it downloads everything from the
 
75
Cheeseshop.
 
76
 
 
77
You do have access to the virtualenv, and you can use this to run individual
 
78
tests, e.g.::
 
79
 
 
80
    % .tox/py27/bin/python -m nose2 -vv -P user
 
81
 
 
82
Use `.tox/py27/bin/python -m nose2 --help` for more options.
 
83
 
73
84
 
74
85
Building for development
75
86
------------------------
76
87
 
 
88
To build Mailman for development purposes, you can create a virtual
 
89
environment outside of tox.  You need to have the `virtualenv`_ program
 
90
installed.
 
91
 
77
92
First, create a virtual environment.  By default ``virtualenv`` uses the
78
93
``python`` executable it finds first on your ``$PATH``.  Make sure this is
79
94
Python 2.7 (just start the interactive interpreter and check the version in
96
111
    % python setup.py develop
97
112
 
98
113
Sit back and have some Kombucha while you wait for everything to download and
99
 
install.  If you have older versions of some of the packages, the installation
100
 
may be interrupted with an error such as::
101
 
 
102
 
    error: Installed distribution zope.interface 3.8.0 conflicts with requirement zope.interface>=4.1.0
103
 
 
104
 
(It appears that this is a defect specific to the ``zope.interface``
105
 
package; it's expected that it should upgrade in this situation.
106
 
However, we cannot rule out similar problems with other packages.)
107
 
 
108
 
This issue can be addressed in two ways.  If you are worried about backward
109
 
compatibility with the installed version of the package for some reason, you
110
 
can restart the process by creating a virtualenv without the
111
 
``--system-site-packages`` option.  This may require installation of duplicates
112
 
of many packages, as only the standard library and packages freshly installed
113
 
in the virtualenv will be available to Python.
114
 
 
115
 
The alternative is to keep the virtualenv installed with
116
 
``--system-site-packages``, explicitly upgrade the package, and then
117
 
restart the installation::
118
 
 
119
 
    % pip install --upgrade zope.interface
120
 
    % python setup.py develop
121
 
 
122
 
Now you can run the test suite via::
123
 
 
124
 
    % nose2 -v
125
 
 
126
 
You should see no failures.  You can also run a subset of the full test suite
127
 
by filter tests on the module or test name using the ``-P`` option::
128
 
 
129
 
    % nose2 -v -P user
 
114
install.
130
115
 
131
116
Build the online docs by running::
132
117
 
249
234
.. _`Postorius documentation`: http://www.pythonhosted.org/postorius/
250
235
.. _`HyperKitty documentation`: https://hyperkitty.readthedocs.org/en/latest/development.html
251
236
.. _`Development Setup Guide`: https://fedorahosted.org/hyperkitty/wiki/DevelopmentSetupGuide
 
237
.. _tox: https://testrun.org/tox/latest/