← Back to branch summary

~parthm/bzr/164450-push-pull-tags

« back to all changes in this revision

Viewing changes to doc/developers/HACKING.txt

Merge lp:bzr.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/HACKING.txt
620
620
Naming
621
621
======
622
622
 
623
 
Functions, methods or members that are "private" to bzrlib are given
 
623
Functions, methods or members that are relatively private are given
624
624
a leading underscore prefix.  Names without a leading underscore are
625
625
public not just across modules but to programmers using bzrlib as an
626
 
API. As a consequence, a leading underscore is appropriate for names
627
 
exposed across modules but that are not to be exposed to bzrlib API
628
 
programmers.
 
626
API. 
629
627
 
630
628
We prefer class names to be concatenated capital words (``TestCase``)
631
629
and variables, methods and functions to be lowercase words joined by
673
671
    may not catch every case but it's still useful sometimes.
674
672
 
675
673
 
 
674
Cleanup methods
 
675
===============
 
676
 
 
677
Often when something has failed later code, including cleanups invoked
 
678
from ``finally`` blocks, will fail too.  These secondary failures are
 
679
generally uninteresting compared to the original exception.  So use the
 
680
``only_raises`` decorator (from ``bzrlib.decorators``) for methods that
 
681
are typically called in ``finally`` blocks, such as ``unlock`` methods.
 
682
For example, ``@only_raises(LockNotHeld, LockBroken)``.  All errors that
 
683
are unlikely to be a knock-on failure from an previous failure should be
 
684
allowed.
 
685
 
 
686
 
676
687
Factories
677
688
=========
678
689
 
847
858
Evolving Interfaces
848
859
===================
849
860
 
850
 
We have a commitment to 6 months API stability - any supported symbol in a
851
 
release of bzr MUST NOT be altered in any way that would result in
 
861
We don't change APIs in stable branches: any supported symbol in a stable
 
862
release of bzr must not be altered in any way that would result in
852
863
breaking existing code that uses it. That means that method names,
853
864
parameter ordering, parameter names, variable and attribute names etc must
854
865
not be changed without leaving a 'deprecated forwarder' behind. This even
860
871
keyword parameter to branch.commit which is a *required* transaction
861
872
object, I should rename the API - i.e. to 'branch.commit_transaction'. 
862
873
 
 
874
  (Actually, that may break code that provides a new implementation of
 
875
  ``commit`` and doesn't expect to receive the parameter.)
 
876
 
863
877
When renaming such supported API's, be sure to leave a deprecated_method (or
864
878
_function or ...) behind which forwards to the new API. See the
865
879
bzrlib.symbol_versioning module for decorators that take care of the