Ticket #4567: lore-core-development-cleanups.diff
| File lore-core-development-cleanups.diff, 18.5 KB (added by Screwtape, 3 years ago) |
|---|
-
doc/core/development/policy/coding-standard.xhtml
diff --git a/doc/core/development/policy/coding-standard.xhtml b/doc/core/development/policy/coding-standard.xhtml index 1dd4af4..1723970 100644
a b 36 36 37 37 <p>Twisted development should always be 38 38 <a href="http://en.wikipedia.org/wiki/Test-driven_development"> 39 test-driven</a>. The complete test suite in t runk@HEADis required to39 test-driven</a>. The complete test suite in the head of the SVN trunk is required to 40 40 be passing on <a href="http://buildbot.twistedmatrix.com/supported"> 41 41 supported platforms</a> at all times. Regressions in the test suite 42 42 are addressed by reverting whatever revisions introduced them. For … … 55 55 the test suite are generally better examples than older parts - check 56 56 when the code you are looking at was written before you use it as an 57 57 example of what you should write). The names of test modules should 58 begin with < q>test_</q> so that they are automatically discoverable by58 begin with <code>test_</code> so that they are automatically discoverable by 59 59 test runners such as Trial. Twisted's unit tests are written using 60 60 <code class="API">twisted.trial</code>, an xUnit library which has been 61 61 extensively customized for use in testing Twisted and Twisted-based … … 527 527 </pre> 528 528 529 529 <p>In this case, <code>callRemote</code> (and any code that uses the 530 **kwargs syntax) must be careful to not use <q>name</q>, <q>phone</q>, or531 any other name that might overlap with a user-provided named parameter.532 Therefore, <code>callRemote</code> is implemented with the following533 signature:</p>530 <code class="python">**kwargs</code> syntax) must be careful to not use 531 <q>name</q>, <q>phone</q>, or any other name that might overlap with 532 a user-provided named parameter. Therefore, <code>callRemote</code> is 533 implemented with the following signature:</p> 534 534 535 535 <pre class="python"> 536 536 def callRemote(self, _name, *args, **kw): … … 545 545 546 546 <h2>Special Methods</h2> 547 547 548 <p>The augmented assignment protocol, defined by __iadd__ and other 548 <p>The augmented assignment protocol, defined by <code 549 class="python">__iadd__</code> and other 549 550 similarly named methods, can be used to allow objects to be modified in 550 551 place or to rebind names if an object is immutable -- both through use 551 552 of the same operator. This can lead to confusing code, which in turn -
doc/core/development/policy/doc-standard.xhtml
diff --git a/doc/core/development/policy/doc-standard.xhtml b/doc/core/development/policy/doc-standard.xhtml index 68ef7c4..ff0d4ce 100644
a b 12 12 13 13 <h2>Allowable Tags</h2> 14 14 15 <p>Please try to restrict your HTML usage to the following tags (all only for the original logical purpose, and not whatever visual effect you see): <code><html></code>, <code><title></code>, <code><head></code>, <code><body></code>, <code><h1></code>, <code><h2</code>, <code><h3></code>, <code><ol></code>, <code><ul></code>, <code><dl></code>, <code><li></code>, <code><dt></code>, <code><dd></code>, <code><p></code>, <code><code></code>, <code><img></code>, <code><blockquote></code>, <code><a></code>, <code><cite></code>, <code><div></code>, <code><span></code>, <code><strong></code>, <code><em></code>, <code><pre></code>, <code><q></code>, <code><table></code>, <code><tr></code>, <code><td></code> and <code><th></code>.</p>15 <p>Please try to restrict your HTML usage to the following tags (all only for the original logical purpose, and not whatever visual effect you see): <code><html></code>, <code><title></code>, <code><head></code>, <code><body></code>, <code><h1></code>, <code><h2</code>, <code><h3></code>, <code><ol></code>, <code><ul></code>, <code><dl></code>, <code><li></code>, <code><dt></code>, <code><dd></code>, <code><p></code>, <code><code></code>, <code><img></code>, <code><blockquote></code>, <code><a></code>, <code><cite></code>, <code><div></code>, <code><span></code>, <code><strong></code>, <code><em></code>, <code><pre></code>, <code><q></code>, <code><table></code>, <code><tr></code>, <code><td></code> and <code><th></code>.</p> 16 16 17 17 <p>Please avoid using the quote sign (<code>"</code>) for quoting, and use the relevant html tags (<code><q></q></code>) -- it is impossible to distinguish right and left quotes with the quote sign, and some more sophisticated output methods work better with that distinction.</p> 18 18 … … 24 24 and <q>shell</q>. For example:</p> 25 25 26 26 <h3><q>python</q></h3> 27 <p>Original markup:</p> 28 <blockquote> 27 29 <pre> 28 29 30 30 <p> 31 For example, this is how one defines a Resource: 32 </p> 31 33 32 34 <pre class="python"> 33 35 from twisted.web import resource 34 36 35 37 class MyResource(resource.Resource): 36 38 def render_GET(self, request): 37 39 return "Hello, world!" 38 40 </pre> 39 41 </pre> 42 </blockquote> 40 43 44 <p>Rendered result:</p> 45 <blockquote> 41 46 <p>For example, this is how one defines a Resource:</p> 42 47 <pre class="python"> 43 48 from twisted.web import resource … … 47 52 return "Hello, world!" 48 53 49 54 </pre> 55 </blockquote> 50 56 51 57 <p>Note that you should never have leading indentation inside a 52 58 <pre> block -- this makes it hard for readers to 53 59 copy/paste the code.</p> 54 60 55 61 <h3><q>python-interpreter</q></h3> 62 <p>Original markup:</p> 63 <blockquote> 56 64 <pre> 57 58 59 60 61 62 63 64 65 65 <pre class="python-interpreter"> 66 &gt;&gt;&gt; from twisted.web import resource 67 &gt;&gt;&gt; class MyResource(resource.Resource): 68 ... def render_GET(self, request): 69 ... return "Hello, world!" 70 ... 71 &gt;&gt;&gt; MyResource().render_GET(None) 72 "Hello, world!" 73 </pre> 66 74 </pre> 75 </blockquote> 67 76 77 <p>Rendered result:</p> 78 <blockquote> 68 79 <pre class="python-interpreter"> 69 80 >>> from twisted.web import resource 70 81 >>> class MyResource(resource.Resource): … … 74 85 >>> MyResource().render_GET(None) 75 86 "Hello, world!" 76 87 </pre> 88 </blockquote> 77 89 78 90 <h3><q>shell</q></h3> 91 <p>Original markup:</p> 92 <blockquote> 79 93 <pre> 80 94 <pre class="shell"> 81 95 $ twistd web --path /var/www 82 96 </pre> 83 97 </pre> 98 </blockquote> 84 99 100 <p>Rendered result:</p> 101 <blockquote> 85 102 <pre class="shell"> 86 103 $ twistd web --path /var/www 87 104 </pre> 105 </blockquote> 88 106 89 107 <h2>Code inside paragraph text</h2> 90 108 … … 103 121 to the module or classname. This is to help keep the documentation 104 122 clearer and less cluttered by allowing links to API docs that don't 105 123 need the module name.</p> 124 <p>Original markup:</p> 125 <blockquote> 106 126 <pre> 107 127 <p> 108 128 To add a <code class="API">twisted.web.widgets.Widget</code> … … 120 140 </p> 121 141 122 142 </pre> 143 </blockquote> 123 144 124 <div class="boxed"> 145 <p>Rendered result:</p> 146 <blockquote> 125 147 <p> 126 148 To add a <code class="API">twisted.web.widgets.Widget</code> 127 149 instance to a <code class="API" base="twisted.web.widgets">Gadget</code> … … 135 157 which is a 136 158 list.) 137 159 </p> 138 139 </div> 160 </blockquote> 140 161 141 162 <h2>Headers</h2> 142 163 -
doc/core/development/policy/svn-dev.xhtml
diff --git a/doc/core/development/policy/svn-dev.xhtml b/doc/core/development/policy/svn-dev.xhtml index ae4ea97..0ee68f9 100644
a b 22 22 23 23 <h2>Checkout</h2> 24 24 25 <p>Subversion tutorials can be found elsewhere, see in particular 25 <p>Subversion tutorials can be found elsewhere, see in particular 26 26 <a href="http://subversion.apache.org/">the Subversion homepage</a>. The 27 27 relevant data you need to check out a copy of the Twisted tree is available on 28 the <a href="http://twistedmatrix.com/trac/wiki/TwistedDevelopment">development 28 the <a href="http://twistedmatrix.com/trac/wiki/TwistedDevelopment">development 29 29 page</a>, and is as follows:</p> 30 30 31 31 <pre class="shell"> … … 35 35 <h2>Alternate tree names</h2> 36 36 37 37 <p>By using <code>svn co svn://svn.twistedmatrix.com/svn/Twisted/trunk 38 otherdir</code>, you can put the workspace tree in a directory other than 38 otherdir</code>, you can put the workspace tree in a directory other than 39 39 <q>Twisted</q>. I do this (with a name like <q>Twisted-Subversion</q>) to 40 40 remind myself that this tree comes from Subversion and not from a released 41 41 version (like <q>Twisted-1.0.5</q>). This practice can cause a few problems, 42 42 because there are a few places in the Twisted tree that need to know where 43 43 the tree starts, so they can add it to <code>sys.path</code> without 44 44 requiring the user manually set their PYTHONPATH. These functions walk the 45 current directory up to the root, looking for a directory named 46 <q>Twisted</q> (sometimes exactly that, sometimes with a 45 current directory up to the root, looking for a directory named 46 <q>Twisted</q> (sometimes exactly that, sometimes with a 47 47 <code>.startswith</code> test). Generally these are test scripts or other 48 48 administrative tools which expect to be launched from somewhere inside the 49 49 tree (but not necessarily from the top).</p> … … 58 58 59 59 <h2>Combinator</h2> 60 60 61 <p>In order to simplify the use of Subversion, we typically use 61 <p>In order to simplify the use of Subversion, we typically use 62 62 <a href="http://divmod.org/trac/wiki/DivmodCombinator">Divmod Combinator</a>. 63 63 You may find it to be useful, too. In particular, because Twisted uses 64 64 branches for almost all feature development, if you plan to contribute to 65 65 Twisted you will probably find Combinator very useful. For more details, 66 see the Combinator website, as well as the 66 see the Combinator website, as well as the 67 67 <a href="http://divmod.org/trac/wiki/UltimateQualityDevelopmentSystem"> 68 68 UQDS</a> page.</p> 69 69 70 70 <h2>Compiling C extensions</h2> 71 71 72 72 <p> 73 There are currently several C extension modules in Twisted: 74 twisted.protocols._c_urlarg, twisted.internet.cfsupport, 75 twisted.internet.iocpreactor._iocp, and twisted.python._epoll. These modules 73 There are currently several C extension modules in Twisted: 74 <code class="python">twisted.protocols._c_urlarg</code>, 75 <code class="python">twisted.internet.cfsupport</code>, 76 <code class="python">twisted.internet.iocpreactor._iocp</code>, 77 and <code class="python">twisted.python._epoll</code>. These modules 76 78 are optional, but you'll have to compile them if you want to experience their 77 79 features, performance improvements, or bugs. There are two approaches. 78 80 </p> 79 81 80 82 <p>The first is to do a regular distutils <code>./setup.py build</code>, which 81 will create a directory under <code>build/</code> to hold both the generated 83 will create a directory under <code>build/</code> to hold both the generated 82 84 <code>.so</code> files as well as a copy of the 600-odd <code>.py</code> files 83 85 that make up Twisted. If you do this, you will need to set your PYTHONPATH to 84 86 something like <code>MyDir/Twisted/build/lib.linux-i686-2.5</code> in order to 85 run code against the Subversion twisted (as opposed to whatever's installed in 87 run code against the Subversion twisted (as opposed to whatever's installed in 86 88 <code>/usr/lib/python2.5</code> or wherever python usually looks). In 87 89 addition, you will need to re-run the <code>build</code> command <em>every 88 90 time</em> you change a <code>.py</code> file. The <code>build/lib.foo</code> … … 95 97 you're using the .py files in place too, removing the confusion a forgotten 96 98 rebuild could cause with the separate build/ directory above. To build the C 97 99 modules in place, do <code>./setup.py build_ext -i</code>. You only need to 98 re-run this command when you change the C files. Note that 100 re-run this command when you change the C files. Note that 99 101 <code>setup.py</code> is not Make, it does not always get the dependencies 100 102 right (<code>.h</code> files in particular), so if you are hacking on the 101 103 cReactor you may need to manually delete the <code>.o</code> files before … … 127 129 <p>This depends upon the <code>.py</code> file having an appropriate 128 130 <q>test-case-name</q> tag that indicates which test cases provide coverage. 129 131 See the <a href="test-standard.xhtml">Test Standards</a> document for 130 details about using <q>test-case-name</q>. In this example, the 132 details about using <q>test-case-name</q>. In this example, the 131 133 <code>twisted.mail.test.test_imap</code> test will be run.</p> 132 134 133 135 <p>Many tests create temporary files in /tmp or ./_trial_temp, but 134 136 everything in /tmp should be deleted when the test finishes. Sometimes these 135 cleanup calls are commented out by mistake, so if you see a stray 136 /tmp/@12345.1 directory, it is probably from test_dirdbm or test_popsicle.137 cleanup calls are commented out by mistake, so if you see a stray 138 <code>/tmp/@12345.1</code> directory, it is probably from <code>test_dirdbm</code> or <code>test_popsicle</code>. 137 139 Look for an <code>rmtree</code> that has been commented out and complain to 138 140 the last developer who touched that file.</p> 139 141 … … 154 156 ./bin/lore/lore -p --config template=doc/howto/template.tpl doc/howto/*.xhtml 155 157 </pre> 156 158 157 <p>To run hlint over a single Lore document, such as 159 <p>To run hlint over a single Lore document, such as 158 160 <code>doc/development/policy/svn-dev.xhtml</code>, do the following. This is 159 161 useful because the HTML conversion may bail without a useful explanation if 160 162 it sees mismatched tags.</p> … … 164 166 </pre> 165 167 166 168 <p>To convert it to HTML (including markup, interpolation of examples, 167 footnote processing, etc), do the following. The results will be placed in 169 footnote processing, etc), do the following. The results will be placed in 168 170 <code>doc/development/policy/svn-dev.html</code>:</p> 169 171 170 172 <pre class="shell"> … … 176 178 include a <q>-l</q> argument to <code>bin/lore/lore</code>. Links in the 177 179 .xhtml file are to .xhtml targets: when the .xhtml is turned into .html, the 178 180 link targets are supposed to be turned into .html also. In addition to this, 179 Lore markup of the form <code class="API">is supposed to181 Lore markup of the form <code><code class="API"></code> is supposed to 180 182 turn into a link to the corresponding API reference page. These links will 181 183 probably be wrong unless the correct base URL is provided to Lore.</p> 182 184 183 185 <h2>Committing and Post-commit Hooks</h2> 184 186 185 <p>Twisted uses a customized 187 <p>Twisted uses a customized 186 188 <a href="http://bazaar.launchpad.net/~exarkun/twisted-trac-integration/trunk/annotate/head%3A/trac-hooks/trac-post-commit-hook"> 187 189 trac-post-commit-hook</a> to enable ticket updates based on svn commit 188 190 logs. When making a branch for a ticket, the branch name should end … … 205 207 My longer description of the changes made. 206 208 </pre> 207 209 208 <p>The <a href="coding-standard.xhtml #commits">Twisted Coding Standard</a>210 <p>The <a href="coding-standard.xhtml">Twisted Coding Standard</a> 209 211 elaborates on commit messages and source control.</p> 210 212 211 213 <h2>Emacs</h2> 212 214 213 <p>A minor mode for development with Twisted using Emacs is available. See 215 <p>A minor mode for development with Twisted using Emacs is available. See 214 216 <code>emacs/twisted-dev.el</code> for several utility functions which make 215 217 it easier to grep for methods, run test cases, etc.</p> 216 218 … … 218 220 219 221 <p>Our support for building Debian packages has fallen into disrepair. We 220 222 would very much like to restore this functionality, but until we do so, if 221 you are interested in this, you are on your own. See 223 you are interested in this, you are on your own. See 222 224 <a href="http://github.com/astraw/stdeb">stdeb</a> for one possible approach to 223 225 this.</p> 224 226 -
doc/core/development/policy/test-standard.xhtml
diff --git a/doc/core/development/policy/test-standard.xhtml b/doc/core/development/policy/test-standard.xhtml index 8df03f6..e1efdfa 100644
a b 129 129 these limitations to be a bug.</p> 130 130 131 131 <p>To make it easy to test as much as possible, some tests may be skipped in 132 certain situations. Individual test cases can raise the 132 certain situations. Individual test cases can raise the 133 133 <code>SkipTest</code> exception to indicate that they should be skipped, and 134 134 the remainder of the test is not run. In the summary (the very last thing 135 135 printed, at the bottom of the test output) the test is counted as a … … 253 253 254 254 <p>Trial provides line coverage information, which is very useful to ensure 255 255 old code has decent coverage. Passing the <code>--coverage</code> option to 256 to Trial will generate the coverage information in a file called 256 to Trial will generate the coverage information in a file called 257 257 <code>coverage</code> which can be found in the <code>_trial_temp</code> 258 258 folder. This option requires Python 2.3.3 or newer.</p> 259 259 … … 310 310 311 311 <li><a href= 312 312 "http://docs.python.org/library/unittest.html" 313 > <code>unittest</code></a> module documentation, in the <a href=313 >unittest</a> module documentation, in the <a href= 314 314 "http://docs.python.org/library">Python Library 315 315 Reference</a>.</li> 316 316