365
When you change bzrlib, please update the relevant documentation for the
366
change you made: Changes to commands should update their help, and
367
possibly end user tutorials; changes to the core library should be
368
reflected in API documentation.
373
If you make a user-visible change, please add a note to the NEWS file.
374
The description should be written to make sense to someone who's just
375
a user of bzr, not a developer: new functions or classes shouldn't be
376
mentioned, but new commands, changes in behaviour or fixed nontrivial
377
bugs should be listed. See the existing entries for an idea of what
380
Within each release, entries in the news file should have the most
381
user-visible changes first. So the order should be approximately:
383
* changes to existing behaviour - the highest priority because the
384
user's existing knowledge is incorrect
385
* new features - should be brought to their attention
386
* bug fixes - may be of interest if the bug was affecting them, and
387
should include the bug number if any
388
* major documentation changes, including fixed documentation bugs
389
* changes to internal interfaces
391
People who made significant contributions to each change are listed in
392
parenthesis. This can include reporting bugs (particularly with good
393
details or reproduction recipes), submitting patches, etc.
395
To help with merging, NEWS entries should be sorted lexicographically
401
The docstring of a command is used by ``bzr help`` to generate help output
402
for the command. The list 'takes_options' attribute on a command is used by
403
``bzr help`` to document the options for the command - the command
404
docstring does not need to document them. Finally, the '_see_also'
405
attribute on a command can be used to reference other related help topics.
410
Functions, methods, classes and modules should have docstrings
411
describing how they are used.
413
The first line of the docstring should be a self-contained sentence.
415
For the special case of Command classes, this acts as the user-visible
416
documentation shown by the help command.
418
The docstrings should be formatted as reStructuredText_ (like this
419
document), suitable for processing using the epydoc_ tool into HTML
422
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
423
.. _epydoc: http://epydoc.sourceforge.net/
362
426
General Guidelines
363
427
==================
511
575
Because Transports work in URLs (as defined earlier), printing the raw URL
512
576
to the user is usually less than optimal. Characters outside the standard
513
577
set are printed as escapes, rather than the real character, and local
514
paths would be printed as ``file://`` URLs. The function
578
paths would be printed as ``file://`` urls. The function
515
579
``unescape_for_display`` attempts to unescape a URL, such that anything
516
580
that cannot be printed in the current encoding stays an escaped URL, but
517
581
valid characters are generated where possible.
added
removed
doc/developers/HACKING.txt
