~certify-web-dev/twisted/certify-staging

<div class="toc"><ol><li><a href="#auto0">Naming</a></li><li><a href="#auto1">Testing</a></li><ul><li><a href="#auto2">Overview</a></li><li><a href="#auto3">Test Suite</a></li></ul><li><a href="#auto4">Copyright Header</a></li><li><a href="#auto5">Whitespace</a></li><li><a href="#auto6">Modules</a></li><li><a href="#auto7">Packages</a></li><li><a href="#auto8">String Formatting Operations</a></li><li><a href="#auto9">Docstrings</a></li><li><a href="#auto10">Comments</a></li><li><a href="#auto11">Versioning</a></li><li><a href="#auto12">Scripts</a></li><li><a href="#auto13">Examples</a></li><li><a href="#auto14">Standard Library Extension Modules</a></li><li><a href="#auto15">Classes</a></li><ul><li><a href="#auto16">New-style Classes</a></li></ul><li><a href="#auto17">Methods</a></li><li><a href="#auto18">Callback Arguments</a></li><li><a href="#auto19">Special Methods</a></li><li><a href="#auto20">Functions</a></li><li><a href="#auto21">Attributes</a></li><li><a href="#auto22">Database</a></li><li><a href="#auto23">C Code</a></li><li><a href="#auto24">Commit Messages</a></li><li><a href="#auto25">Source Control</a></li><li><a href="#auto26">Fallback</a></li><li><a href="#auto27">Recommendations</a></li></ol></div>

<h2>Naming<a name="auto0"/></h2>

Try to choose names which are both easy to remember and

meaningful. Some silliness is OK at the module naming level

(see <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.html" title="twisted.spread">twisted.spread</a></code>...) but when

choosing class names, be as precise as possible.

Try to avoid overloaded terms. This rule is often broken,

since it is incredibly difficult, as most normal words have

already been taken by some other software. More importantly,

try to avoid meaningless words. In particular, words like

<q>handler</q>, <q>processor</q>, <q>engine</q>, <q>manager</q>

and <q>component</q> don't really indicate what something does,

only that it does something.

Use American spelling in both names and docstrings. For compound

technical terms such as 'filesystem', use a non-hyphenated spelling in

both docstrings and code in order to avoid unnecessary

capitalization.

<h2>Testing<a name="auto1"/></h2>

<h3>Overview<a name="auto2"/></h3>

Twisted development should always be

test-driven</a>. The complete test suite in trunk@HEAD is required to

be passing on <a href="http://buildbot.twistedmatrix.com/supported" shape="rect">

supported platforms</a> at all times. Regressions in the test suite

are addressed by reverting whatever revisions introduced them. For

complete documentation about testing Twisted itself, refer to the

<a href="test-standard.html" shape="rect">Test Standard</a>. What follows is

intended to be a synopsis of the most important points.

<h3>Test Suite<a name="auto3"/></h3>

The Twisted test suite is spread across many subpackages of the

<code>twisted</code> package. Many tests are in

<code>twisted.test</code>. Others can be found at places such as

<code>twisted.web.test</code> or <code>twisted.internet.test</code>.

Parts of the Twisted test suite may serve as good examples of how to

write tests for Twisted or for Twisted-based libraries (newer parts of

the test suite are generally better examples than older parts - check

when the code you are looking at was written before you use it as an

example of what you should write). The names of test modules should

begin with <q>test_</q> so that they are automatically discoverable by

test runners such as Trial. Twisted's unit tests are written using

<code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.trial.html" title="twisted.trial">twisted.trial</a></code>, an xUnit library which has been

extensively customized for use in testing Twisted and Twisted-based

libraries.

Implementation (ie, non-test) source files should begin with a

<code>test-case-name</code> tag which gives the name of any test

modules or packages which exercise them. This lets tools discover a

subset of the entire test suite which they can run first to find tests

which might be broken by a particular change.

It is strongly suggested that developers learn to use Emacs, and use

the <code>twisted-dev.el</code> file included in the TwistedEmacs

package to bind the F9 key to <q>run unit tests</q> and bang on it

frequently. Support for other editors is unavailable at this time but

we would love to provide it.

To run the whole Twisted test without using emacs, use trial:

$ bin/trial twisted

</pre>

To run an individual test module, such as

<code>twisted/mail/test/test_pop3.py</code>, specify the module

name:

$ bin/trial twisted.mail.test.test_pop3

</pre>

To run the tests associated with a particular implementation file,

such as <code>twisted/mail/pop3.py</code>, use the

<code>testmodule</code> option:

$ bin/trial twisted/mail/pop3.py

100

</pre>

101

102

All unit test methods should have docstrings specifying at a high

103

level the intent of the test. That is, a description that users of the

104

method would understand.

105

106

If you modify, or write a new, HOWTO, please read the <a href="http://twistedmatrix.com/trac/wiki/TwistedLore" shape="rect">Lore</a>

107

documentation to learn how to format the docs.

108

109

<h2>Copyright Header<a name="auto4"/></h2>

110

111

Whenever a new file is added to the repository, add the following

112

license header at the top of the file, including the year the file was

113

added. For example:

114

115

<pre class="python">1

116

117

118

# See LICENSE for details.

119

</pre>

120

121

When you update existing files, make sure the year in the copyright

122

header is up to date as well. You should add a new copyright header when

123

it's completely missing in the file that is being edited.

124

125

<h2>Whitespace<a name="auto5"/></h2>

126

127

Indentation is 4 spaces per indent. Tabs are not allowed. It

128

is preferred that every block appear on a new line, so that

129

control structure indentation is always visible.

130

131

Lines are flowed at 79 columns. They must not have trailing

132

whitespace. Long lines must be wrapped using implied line continuation

133

inside parentheses; backslashes aren't allowed. To handle long import

134

lines, please repeat the import like this:

135

136

<pre class="python">1

137

138

from very.long.package import foo, bar, baz

139

from very.long.package import qux, quux, quuux

140

</pre>

141

142

Top-level classes and functions must be separated with 3 blank lines,

143

and class-level functions with 2 blank lines. The control-L (i.e. ^L) form

144

feed character must not be used.

145

146

<h2>Modules<a name="auto6"/></h2>

147

148

Modules must be named in all lower-case, preferably short,

149

single words. If a module name contains multiple words, they

150

may be separated by underscores or not separated at all.

151

152

Modules must have a copyright message, a docstring and a

153

reference to a test module that contains the bulk of its tests.

154

Use this template:

155

156

<div class="py-listing"><pre> 1

157

158

159

160

161

162

163

164

165

166

167

168

# -*- test-case-name: <test module> -*-

169

170

171

# See LICENSE for details.

172

173

174

"""

175

Docstring goes here.

176

"""

177

178

179

__all__ = []

180

</pre><div class="caption">Source listing - <a href="../listings/new_module_template.py">../listings/new_module_template.py</a></div></div>

181

182

In most cases, modules should contain more than one class,

183

function, or method; if a module contains only one object,

184

consider refactoring to include more related functionality in

185

that module.

186

187

Depending on the situation, it is acceptable to have imports that

188

look like this:

189

<pre class="python">1

190

from twisted.internet.defer import Deferred

191

</pre>

192

or like this:

193

<pre class="python">1

194

from twisted.internet import defer

195

</pre>

196

That is, modules should import modules or classes and

197

functions, but not packages.

198

199

Wildcard import syntax may not be used by code in Twisted. These

200

imports lead to code which is difficult to read and maintain by

201

introducing complexity which strains human readers and automated tools

202

alike. If you find yourself with many imports to make from a single

203

module and wish to save typing, consider importing the module itself,

204

rather than its attributes.

205

206

Relative imports (or sibling imports) may not be

207

used by code in Twisted. Relative imports allow certain circularities

208

to be introduced which can ultimately lead to unimportable modules or

209

duplicate instances of a single module. Relative imports also make the

210

task of refactoring more difficult.

211

212

In case of local names conflicts due to import, use the <code>as</code>

213

syntax, for example:

214

<pre class="python">1

215

from twisted.trial import util as trial_util

216

</pre>

217

218

The encoding must always be ASCII, so no coding cookie is necessary.

219

220

<h2>Packages<a name="auto7"/></h2>

221

222

Package names should follow the same conventions as module

223

names. All modules must be encapsulated in some package. Nested

224

packages may be used to further organize related modules.

225

226

<code>__init__.py</code> must never contain anything other than a

227

docstring and (optionally) an <code>__all__</code> attribute. Packages are

228

not modules and should be treated differently. This rule may be

229

broken to preserve backwards compatibility if a module is made

230

into a nested package as part of a refactoring.

231

232

If you wish to promote code from a module to a package, for

233

example, to break a large module out into several smaller

234

files, the accepted way to do this is to promote from within

235

the module. For example,

236

237

<pre class="python">1

238

239

240

241

242

243

244

245

246

# parent/

247

# --- __init__.py ---

248

import child

249

250

# --- child.py ---

251

import parent

252

class Foo:

253

pass

254

parent.Foo = Foo

255

</pre>

256

257

Every package should be added to the list in

258

<code class="shell">setup.py</code>.

259

260

Packages must not depend circularly upon each other. To simplify

261

maintaining this state, packages must also not import each other

262

circularly. While this applies to all packages within Twisted, one

263

<code>twisted.python</code> deserves particular attention, as it may

264

not depend on any other Twisted package.

265

266

<h2>String Formatting Operations<a name="auto8"/></h2>

267

268

When using <a href="http://docs.python.org/lib/typesseq-strings.html" shape="rect">string formatting

269

operations</a> like <code>formatString % values</code> you should always

270

use a tuple if you're using non-mapping <code>values</code>. This is to

271

avoid unexpected behavior when you think you're passing in a single value,

272

but the value is unexpectedly a tuple, e.g.:

273

274

<pre class="python">1

275

276

def foo(x):

277

return "Hi %s\n" % x

278

</pre>

279

280

The example shows you can pass in <code>foo("foo")</code> or

281

<code>foo(3)</code> fine, but if you pass in <code>foo((1,2))</code>,

282

it raises a <code>TypeError</code>. You should use this instead:

283

284

<pre class="python">1

285

286

def foo(x):

287

return "Hi %s\n" % (x,)

288

</pre>

289

290

<h2>Docstrings<a name="auto9"/></h2>

291

292

Docstrings should always be used to describe the

293

purpose of methods, functions, classes, and modules.

294

295

Docstrings are never to be used to provide semantic

296

information about an object; this rule may be violated if the

297

code in question is to be used in a system where this is a

298

requirement (such as Zope).

299

300

Docstrings should be indented to the level of the code they

301

are documenting.

302

303

Docstrings should be triple-quoted. The opening and the closing of the

304

docstrings should be on a line by themselves. For example:

305

<pre class="python">1

306

307

308

309

310

311

312

313

class Ninja(object):

314

"""

315

A L{Ninja} is a warrior specializing in various unorthodox arts of war.

316

"""

317

def attack(self, someone):

318

"""

319

Attack C{someone} with this L{Ninja}'s shuriken.

320

"""

321

</pre>

322

323

324

Docstrings should be written in epytext format; more

325

documentation is available in the

326

<a href="http://epydoc.sourceforge.net/epytext.html" shape="rect">Epytext Markup Language documentation</a>.

327

328

Additionally, to accommodate emacs users:

329

330

<ul>

331

<li>Single quotes of the type of the docstring's triple-quote

332

should be escaped. This will prevent font-lock from

333

accidentally fontifying large portions of the file as a

334

string.</li>

335

336

<li>Code examples in docstrings should be prefixed by the |

337

character. This will prevent IM-Python from regarding sample

338

code as real functions, methods, and classes.</li>

339

</ul>

340

341

For example,

342

<pre class="python"> 1

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

def foo2bar(f):

366

"""

367

Convert L{foo}s to L{bar}s.

368

369

A function that should be used when you have a C{foo} but you want a

370

C{bar}; note that this is a non-destructive operation. If this method

371

can't convert the C{foo} to a C{bar} it will raise a L{FooException}.

372

373

@param f: C{foo}

374

@type f: str

375

376

For example::

377

378

| import wombat

379

| def sample(something):

380

| f = something.getFoo()

381

| f.doFooThing()

382

| b = wombat.foo2bar(f)

383

| b.doBarThing()

384

| return b

385

386

"""

387

# Optionally, actual code can go here.

388

</pre>

389

390

<h2>Comments<a name="auto10"/></h2>

391

392

Comments marked with XXX or TODO must contain a reference to the

393

associated ticket.

394

395

<h2>Versioning<a name="auto11"/></h2>

396

397

The API documentation should be marked up with version information.

398

When a new API is added the class should be marked with the epytext

399

<code class="shell">@since:</code> field including the version number when

400

the change was introduced, eg. <code class="shell">@since: 8.1</code>.

401

402

<h2>Scripts<a name="auto12"/></h2>

403

404

For each <q>script</q>, that is, a program you expect a Twisted user

405

to run from the command-line, the following things must be done:

406

407

<ol>

408

<li>Write a module in <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.scripts.html" title="twisted.scripts">twisted.scripts</a></code>

409

which contains a callable global named <code>run</code>. This

410

will be called by the command line part with no arguments (it

411

will usually read <code>sys.argv</code>). Feel free to write more

412

functions or classes in this module, if you feel they are useful

413

to others.</li>

414

415

<li>Create a file which contains a shebang line for Python. For Twisted

416

Core, this file should be placed in the <code>bin/</code> directory; for

417

example, <code>bin/twistd</code>. For sub-projects, it should be placed

418

in <code>bin/<subproject></code>; for example, the key-generation tool

419

for the Conch sub-project is in <code>bin/conch/ckeygen</code>.

420

<pre class="python">1

421

#!/usr/bin/env python

422

</pre></li>

423

424

To make sure that the script is portable across different UNIX like

425

operating systems we use the <code>/usr/bin/env</code> command. The env

426

command allows you to run a program in a modified environment. That way

427

you don't have to search for a program via the <code>PATH</code> environment

428

variable. This makes the script more portable but note that it is not a

429

foolproof method. Always make sure that <code>/usr/bin/env</code> exists or

430

use a softlink/symbolic link to point it to the correct path. Python's

431

distutils will rewrite the shebang line upon installation so this policy

432

only covers the source files in version control.

433

434

<li>Add the Twisted running-from-SVN header:

435

<pre class="python">1

436

437

438

439

440

441

442

443

444

### Twisted Preamble

445

# This makes sure that users don't have to set up their environment

446

# specially in order to run these programs from bin/.

447

import sys, os, string

448

if string.find(os.path.abspath(sys.argv[0]), os.sep+'Twisted') != -1:

449

sys.path.insert(0, os.path.normpath(os.path.join(os.path.abspath(sys.argv[0]), os.pardir, os.pardir)))

450

if not hasattr(os, "getuid") or os.getuid() != 0:

451

452

### end of preamble

453

</pre></li>

454

455

<li>And end with:

456

<pre class="python">1

457

458

from twisted.scripts.yourmodule import run

459

run()

460

</pre></li>

461

462

<li>Write a manpage and add it to the <code class="shell">man</code> folder

463

of a subproject's <code class="shell">doc</code> folder. On Debian systems

464

you can find a skeleton example of a manpage in

465

<code>/usr/share/doc/man-db/examples/manpage.example</code>.</li>

466

</ol>

467

468

This will insure your program will work correctly for users of SVN,

469

Windows releases and Debian packages.

470

471

<h2>Examples<a name="auto13"/></h2>

472

473

For example scripts you expect a Twisted user

474

to run from the command-line, add this Python shebang line at the top

475

of the file:

476

<pre class="python">1

477

#!/usr/bin/env python

478

</pre>

479

480

<h2>Standard Library Extension Modules<a name="auto14"/></h2>

481

482

When using the extension version of a module for which there is also

483

a Python version, place the import statement inside a try/except block,

484

and import the Python version if the import fails. This allows code to

485

work on platforms where the extension version is not available. For

486

example:

487

488

<pre class="python">1

489

490

491

492

try:

493

import cPickle as pickle

494

except ImportError:

495

import pickle

496

</pre>

497

498

Use the "as" syntax of the import statement as well, to set

499

the name of the extension module to the name of the Python module.

500

501

Some modules don't exist across all supported Python versions. For

502

example, Python 2.3's <code>sets</code> module was deprecated in Python 2.6

503

in favor of the <code>set</code> and <code>frozenset</code> builtins. When

504

you need to use sets or frozensets in your code, please use

505

<code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.python.compat.set.html" title="twisted.python.compat.set">twisted.python.compat.set</a></code> and

506

<code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.python.compat.frozenset.html" title="twisted.python.compat.frozenset">twisted.python.compat.frozenset</a></code>. There are some

507

differences between <code>sets.Set</code> and <code>set</code>, that are

508

explained in the

509

<a href="http://www.python.org/dev/peps/pep-0218/" shape="rect">set PEP</a>. Please be

510

sure to not rely on the behavior of one or the other implementation.

511

512

513

<h2>Classes<a name="auto15"/></h2>

514

515

Classes are to be named in mixed case, with the first letter

516

capitalized; each word separated by having its first letter

517

capitalized. Acronyms should be capitalized in their entirety.

518

Class names should not be prefixed with the name of the module they are

519

in. Examples of classes meeting this criteria:

520

521

<ul>

522

<li>twisted.spread.pb.ViewPoint</li>

523

<li>twisted.parser.patterns.Pattern</li>

524

</ul>

525

526

Examples of classes not meeting this criteria:

527

528

<ul>

529

<li>event.EventHandler</li>

530

<li>main.MainGadget</li>

531

</ul>

532

533

An effort should be made to prevent class names from clashing

534

with each other between modules, to reduce the need for

535

qualification when importing. For example, a Service subclass

536

for Forums might be named twisted.forum.service.ForumService,

537

and a Service subclass for Words might be

538

twisted.words.service.WordsService. Since neither of these

539

modules are volatile (see above) the classes may be

540

imported directly into the user's namespace and not cause

541

confusion.

542

543

<h3>New-style Classes<a name="auto16"/></h3>

544

545

Classes and instances in Python come in two flavors: old-style or

546

classic, and new-style. Up to Python 2.1, old-style classes were the

547

only flavour available to the user, new-style classes were introduced

548

in Python 2.2 to unify classes and types. All classes added to Twisted

549

should be written as new-style classes. If <code class="python">x</code>

550

is an instance of a new-style class, then <code class="python">type(x)</code>

551

is the same as <code class="python">x.__class__</code>.

552

553

<h2>Methods<a name="auto17"/></h2>

554

555

Methods should be in mixed case, with the first letter lower

556

case, each word separated by having its first letter

557

capitalized. For example, <code>someMethodName</code>,

558

<code>method</code>.

559

560

Sometimes, a class will dispatch to a specialized sort of

561

method using its name; for example, twisted.reflect.Accessor.

562

In those cases, the type of method should be a prefix in all

563

lower-case with a trailing underscore, so method names will

564

have an underscore in them. For example, <code>get_someAttribute</code>.

565

Underscores in method names in twisted code are therefore

566

expected to have some semantic associated with them.

567

568

Some methods, in particular <code>addCallback</code> and its

569

cousins return self to allow for chaining calls. In this case,

570

wrap the chain in parenthesis, and start each chained call on

571

a separate line, for example:

572

573

<pre class="python">1

574

575

576

577

return (foo()

578

.addCallback(bar)

579

.addCallback(thud)

580

.addCallback(wozers))

581

</pre>

582

583

<h2>Callback Arguments<a name="auto18"/></h2>

584

585

There are several methods whose purpose is to help the user set up

586

callback functions, for example <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.defer.Deferred.addCallback.html" title="twisted.internet.defer.Deferred.addCallback">Deferred.addCallback</a></code> or the

587

reactor's <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.base.ReactorBase.callLater.html" title="twisted.internet.base.ReactorBase.callLater">callLater</a></code> method. To make

588

access to the callback as transparent as possible, most of these methods

589

use <code class="python">**kwargs</code> to capture arbitrary arguments

590

that are destined for the user's callback. This allows the call to the

591

setup function to look very much like the eventual call to the target

592

callback function.

593

594

In these methods, take care to not have other argument names that will

595

<q>steal</q> the user's callback's arguments. When sensible, prefix these

596

<q>internal</q> argument names with an underscore. For example, <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.pb.RemoteReference.callRemote.html" title="twisted.spread.pb.RemoteReference.callRemote">RemoteReference.callRemote</a></code> is

597

meant to be called like this:

598

599

<pre class="python">1

600

601

602

603

604

myref.callRemote("addUser", "bob", "555-1212")

605

606

# on the remote end, the following method is invoked:

607

def addUser(name, phone):

608

...

609

</pre>

610

611

where <q>addUser</q> is the remote method name. The user might also

612

choose to call it with named parameters like this:

613

614

<pre class="python">1

615

myref.callRemote("addUser", name="bob", phone="555-1212")

616

</pre>

617

618

In this case, <code>callRemote</code> (and any code that uses the

619

**kwargs syntax) must be careful to not use <q>name</q>, <q>phone</q>, or

620

any other name that might overlap with a user-provided named parameter.

621

Therefore, <code>callRemote</code> is implemented with the following

622

signature:

623

624

<pre class="python">1

625

626

def callRemote(self, _name, *args, **kw):

627

...

628

</pre>

629

630

Do whatever you can to reduce user confusion. It may also be

631

appropriate to <code class="python">assert</code> that the kwargs

632

dictionary does not contain parameters with names that will eventually

633

cause problems.

634

635

636

<h2>Special Methods<a name="auto19"/></h2>

637

638

The augmented assignment protocol, defined by __iadd__ and other

639

similarly named methods, can be used to allow objects to be modified in

640

place or to rebind names if an object is immutable -- both through use

641

of the same operator. This can lead to confusing code, which in turn

642

leads to buggy code. For this reason, methods of the augmented

643

assignment protocol should not be used in Twisted.

644

645

<h2>Functions<a name="auto20"/></h2>

646

647

Functions should be named similiarly to methods.

648

649

Functions or methods which are responding to events to

650

complete a callback or errback should be named <code>_cbMethodName</code> or

651

<code>_ebMethodName</code>, in order to distinguish them from normal

652

methods.

653

654

<h2>Attributes<a name="auto21"/></h2>

655

656

Attributes should be named similarly to functions and

657

methods. Attributes should be named descriptively; attribute

658

names like <code>mode</code>, <code>type</code>, and

659

<code>buf</code> are generally discouraged. Instead, use

660

<code>displayMode</code>, <code>playerType</code>, or

661

<code>inputBuffer</code>.

662

663

Do not use Python's <q>private</q> attribute syntax; prefix

664

non-public attributes with a single leading underscore. Since

665

several classes have the same name in Twisted, and they are

666

distinguished by which package they come from, Python's

667

double-underscore name mangling will not work reliably in some

668

cases. Also, name-mangled private variables are more difficult

669

to address when unit testing or persisting a class.

670

671

An attribute (or function, method or class) should be

672

considered private when one or more of the following conditions

673

are true:

674

675

<ul>

676

<li>The attribute represents intermediate state which is not

677

always kept up-to-date.</li>

678

679

<li>Referring to the contents of the attribute or otherwise

680

maintaining a reference to it may cause resources to

681

leak.</li>

682

683

<li>Assigning to the attribute will break internal

684

assumptions.</li>

685

686

<li>The attribute is part of a known-to-be-sub-optimal

687

interface and will certainly be removed in a future

688

release.</li>

689

</ul>

690

691

692

<h2>Database<a name="auto22"/></h2>

693

694

Database tables will be named with plural nouns.

695

696

Database columns will be named with underscores between

697

words, all lower case, since most databases do not distinguish

698

between case.

699

700

Any attribute, method argument, or method name that

701

corresponds directly to a column in the database will

702

be named exactly the same as that column, regardless of other

703

coding conventions surrounding that circumstance.

704

705

All SQL keywords should be in upper case.

706

707

708

709

Wherever possible, C code should be optional, and the

710

default python implementation should be maintained in tandem

711

with it. C code should be strict ANSI C, and

712

must build using GCC as well as Visual Studio

713

for Windows, and really shouldn't have any problems with other

714

compilers either. Don't do anything tricky.

715

716

C code should only be used for efficiency, not for binding

717

to external libraries. If your particular code is not

718

frequently run, write it in Python. If you require the use of

719

an external library, develop a separate, external bindings

720

package and make your twisted code depend on it.

721

722

<h2>Commit Messages<a name="auto24"/></h2>

723

724

The commit messages are being distributed in a myriad of ways. Because

725

of that, you need to observe a few simple rules when writing a commit

726

message.

727

728

The first line of the message is being used as both the subject of

729

the commit email and the announcement on #twisted. Therefore, it should

730

be short (aim for < 80 characters) and descriptive -- and must be

731

able to stand alone (it is best if it is a complete sentence). The rest

732

of the e-mail should be separated with hard line breaks into

733

short lines (< 70 characters). This is free-format, so you can do

734

whatever you like here.

735

736

Commit messages should be about what, not how: we can

737

get how from SVN diff. Explain reasons for commits, and what they

738

affect.

739

740

Each commit should be a single logical change, which is internally

741

consistent. If you can't summarize your changes in one short line, this

742

is probably a sign that they should be broken into multiple checkins.

743

744

<h2>Source Control<a name="auto25"/></h2>

745

746

Twisted currently uses Subversion for source control. All

747

development should occur using branches; when a task is

748

considered complete another Twisted developer may review it and if no

749

problems are found, it may be merged into trunk. The Twisted wiki has <a href="http://twistedmatrix.com/trac/wiki/TwistedDevelopment" shape="rect">a start</a>.

750

Branches must be used for major development. Branches

751

should be managed using <a href="http://divmod.org/trac/wiki/DivmodCombinator" shape="rect">Combinator</a> (but

752

if you can manage them in some other way without anyone noticing, knock

753

yourself out).

754

755

Certain features of Subversion should be avoided.

756

757

<ul>

758

<li>

759

760

Do not set the <code class="shell">svn:ignore</code> property on any

761

file or directory. What you wish to ignore, others may wish to examine.

762

What others may wish you ignore, you may wish you examine.

763

<code class="shell"> svn:ignore </code> will affect everyone who uses

764

the repository, and so it is not the right mechanism to express personal

765

preferences.

766

767

If you wish to ignore certain files use the <code class="shell">

768

global-ignores </code> feature of <code class="shell">

769

~/.subversion/config </code>, for example:

770

771

772

[miscellany]

773

global-ignores = dropin.cache *.pyc *.pyo *.o *.lo *.la #*# .*.rej *.rej .*~

774

</pre>

775

776

</li>

777

</ul>

778

779

<h2>Fallback<a name="auto26"/></h2>

780

781

In case of conventions not enforced in this document, the reference

782

documents to use in fallback is

783

<a href="http://www.python.org/dev/peps/pep-0008/" shape="rect">PEP 8</a> for Python

784

code and <a href="http://www.python.org/dev/peps/pep-0007/" shape="rect">PEP 7</a> for

785

C code. For example, the paragraph Whitespace in Expressions and

786

Statements in PEP 8 describes what should be done in Twisted

787

code.

788

789

<h2>Recommendations<a name="auto27"/></h2>

790

791

These things aren't necessarily standardizeable (in that

792

code can't be easily checked for compliance) but are a good

793

idea to keep in mind while working on Twisted.

794

795

If you're going to work on a fragment of the Twisted

796

codebase, please consider finding a way that you would use

797

such a fragment in daily life. Using a Twisted Web server on your

798

website encourages you to actively maintain and improve your code,

799

as the little everyday issues with using it become apparent.

800

801

Twisted is a big codebase! If you're

802

refactoring something, please make sure to recursively grep for

803

the names of functions you're changing. You may be surprised to

804

learn where something is called. Especially if you are moving

805

or renaming a function, class, method, or module, make sure

806

that it won't instantly break other code.

807

808

</div>

809

810

<a href="../../howto/index.html">Index</a>

811

Version: 9.0.0

812

</body>

813

</html>

b'\\ No newline at end of file'

Older »