349
343
test was not run, rather than just returning which makes it look as if it
350
344
was run and passed.
352
Several different cases are distinguished:
355
Generic skip; the only type that was present up to bzr 0.18.
358
The test doesn't apply to the parameters with which it was run.
359
This is typically used when the test is being applied to all
360
implementations of an interface, but some aspects of the interface
361
are optional and not present in particular concrete
362
implementations. (Some tests that should raise this currently
363
either silently return or raise TestSkipped.) Another option is
364
to use more precise parameterization to avoid generating the test
368
**(Not implemented yet)**
369
The test can't be run because of an inherent limitation of the
370
environment, such as not having symlinks or not supporting
374
The test can't be run because a dependency (typically a Python
375
library) is not available in the test environment. These
376
are in general things that the person running the test could fix
377
by installing the library. It's OK if some of these occur when
378
an end user runs the tests or if we're specifically testing in a
379
limited environment, but a full test should never see them.
382
The test exists but is known to fail, for example because the
383
code to fix it hasn't been run yet. Raising this allows
384
you to distinguish these failures from the ones that are not
385
expected to fail. This could be conditionally raised if something
386
is broken on some platforms but not on others.
388
We plan to support three modes for running the test suite to control the
389
interpretation of these results. Strict mode is for use in situations
390
like merges to the mainline and releases where we want to make sure that
391
everything that can be tested has been tested. Lax mode is for use by
392
developers who want to temporarily tolerate some known failures. The
393
default behaviour is obtained by ``bzr selftest`` with no options, and
394
also (if possible) by running under another unittest harness.
396
======================= ======= ======= ========
397
result strict default lax
398
======================= ======= ======= ========
399
TestSkipped pass pass pass
400
TestNotApplicable pass pass pass
401
TestPlatformLimit pass pass pass
402
TestDependencyMissing fail pass pass
403
KnownFailure fail pass pass
404
======================= ======= ======= ========
407
Test feature dependencies
408
-------------------------
410
Rather than manually checking the environment in each test, a test class
411
can declare its dependence on some test features. The feature objects are
412
checked only once for each run of the whole test suite.
414
For historical reasons, as of May 2007 many cases that should depend on
415
features currently raise TestSkipped.)
346
A subtly different case is a test that should run, but can't run in the
347
current environment. This covers tests that can only run in particular
348
operating systems or locales, or that depend on external libraries. Here
349
we want to inform the user that they didn't get full test coverage, but
350
they possibly could if they installed more libraries. These are expressed
351
as a dependency on a feature so we can summarise them, and so that the
352
test for the feature is done only once. (For historical reasons, as of
353
May 2007 many cases that should depend on features currently raise
354
TestSkipped.) The typical use is::
419
356
class TestStrace(TestCaseWithTransport):
421
358
_test_needs_features = [StraceFeature]
423
This means all tests in this class need the feature. The feature itself
360
which means all tests in this class need the feature. The feature itself
424
361
should provide a ``_probe`` method which is called once to determine if
427
These should generally be equivalent to either TestDependencyMissing or
428
sometimes TestPlatformLimit.
438
372
fix for it, or if something works on Unix but not on Windows.
441
Testing exceptions and errors
442
-----------------------------
444
It's important to test handling of errors and exceptions. Because this
445
code is often not hit in ad-hoc testing it can often have hidden bugs --
446
it's particularly common to get NameError because the exception code
447
references a variable that has since been renamed.
449
.. TODO: Something about how to provoke errors in the right way?
451
In general we want to test errors at two levels:
453
1. A test in ``test_errors.py`` checking that when the exception object is
454
constructed with known parameters it produces an expected string form.
455
This guards against mistakes in writing the format string, or in the
456
``str`` representations of its parameters. There should be one for
457
each exception class.
459
2. Tests that when an api is called in a particular situation, it raises
460
an error of the expected class. You should typically use
461
``assertRaises``, which in the Bazaar test suite returns the exception
462
object to allow you to examine its parameters.
464
In some cases blackbox tests will also want to check error reporting. But
465
it can be difficult to provoke every error through the commandline
466
interface, so those tests are only done as needed -- eg in response to a
467
particular bug or if the error is reported in an unusual way(?) Blackbox
468
tests should mostly be testing how the command-line interface works, so
469
should only test errors if there is something particular to the cli in how
470
they're displayed or handled.
476
The Python ``warnings`` module is used to indicate a non-fatal code
477
problem. Code that's expected to raise a warning can be tested through
480
The test suite can be run with ``-Werror`` to check no unexpected errors
483
However, warnings should be used with discretion. It's not an appropriate
484
way to give messages to the user, because the warning is normally shown
485
only once per source line that causes the problem. You should also think
486
about whether the warning is serious enought that it should be visible to
487
users who may not be able to fix it.
490
Interface implementation testing and test scenarios
491
---------------------------------------------------
493
There are several cases in Bazaar of multiple implementations of a common
494
conceptual interface. ("Conceptual" because
495
it's not necessary for all the implementations to share a base class,
496
though they often do.) Examples include transports and the working tree,
497
branch and repository classes.
499
In these cases we want to make sure that every implementation correctly
500
fulfils the interface requirements. For example, every Transport should
501
support the ``has()`` and ``get()`` and ``clone()`` methods. We have a
502
sub-suite of tests in ``test_transport_implementations``. (Most
503
per-implementation tests are in submodules of ``bzrlib.tests``, but not
504
the transport tests at the moment.)
506
These tests are repeated for each registered Transport, by generating a
507
new TestCase instance for the cross product of test methods and transport
508
implementations. As each test runs, it has ``transport_class`` and
509
``transport_server`` set to the class it should test. Most tests don't
510
access these directly, but rather use ``self.get_transport`` which returns
511
a transport of the appropriate type.
513
The goal is to run per-implementation only tests that relate to that
514
particular interface. Sometimes we discover a bug elsewhere that happens
515
with only one particular transport. Once it's isolated, we can consider
516
whether a test should be added for that particular implementation,
517
or for all implementations of the interface.
519
The multiplication of tests for different implementations is normally
520
accomplished by overriding the ``test_suite`` function used to load
521
tests from a module. This function typically loads all the tests,
522
then applies a TestProviderAdapter to them, which generates a longer
523
suite containing all the test variations.
529
Some utilities are provided for generating variations of tests. This can
530
be used for per-implementation tests, or other cases where the same test
531
code needs to run several times on different scenarios.
533
The general approach is to define a class that provides test methods,
534
which depend on attributes of the test object being pre-set with the
535
values to which the test should be applied. The test suite should then
536
also provide a list of scenarios in which to run the tests.
538
Typically ``multiply_tests_from_modules`` should be called from the test
539
module's ``test_suite`` function.
542
376
Essential Domain Classes
543
377
########################
638
472
callers will at least get an AttributeError rather than weird results.
641
Deprecation decorators
642
----------------------
644
``bzrlib.symbol_versioning`` provides decorators that can be attached to
645
methods, functions, and other interfaces to indicate that they should no
648
To deprecate a static method you must call ``deprecated_function``
649
(**not** method), after the staticmethod call::
652
@deprecated_function(zero_ninetyone)
653
def create_repository(base, shared=False, format=None):
655
When you deprecate an API, you should not just delete its tests, because
656
then we might introduce bugs in them. If the API is still present at all,
657
it should still work. The basic approach is to use
658
``TestCase.applyDeprecated`` which in one step checks that the API gives
659
the expected deprecation message, and also returns the real result from
660
the method, so that tests can keep running.
662
475
Coding Style Guidelines
663
476
=======================
668
``hasattr`` should not be used because it swallows exceptions including
669
``KeyboardInterrupt``. Instead, say something like ::
671
if getattr(thing, 'name', None) is None
677
478
Please write PEP-8__ compliant code.
679
__ http://www.python.org/peps/pep-0008.html
681
480
One often-missed requirement is that the first line of docstrings
682
481
should be a self-contained one-sentence summary.
684
We use 4 space indents for blocks, and never use tab characters. (In vim,
687
Lines should be no more than 79 characters if at all possible.
688
Lines that continue a long statement may be indented in either of
691
within the parenthesis or other character that opens the block, e.g.::
697
or indented by four spaces::
703
The first is considered clearer by some people; however it can be a bit
704
harder to maintain (e.g. when the method name changes), and it does not
705
work well if the relevant parenthesis is already far to the right. Avoid
708
self.legbone.kneebone.shinbone.toebone.shake_it(one,
714
self.legbone.kneebone.shinbone.toebone.shake_it(one,
720
self.legbone.kneebone.shinbone.toebone.shake_it(
723
For long lists, we like to add a trailing comma and put the closing
724
character on the following line. This makes it easier to add new items in
727
from bzrlib.goo import (
733
There should be spaces between function paramaters, but not between the
734
keyword name and the value::
736
call(1, 3, cheese=quark)
740
;(defface my-invalid-face
741
; '((t (:background "Red" :underline t)))
742
; "Face used to highlight invalid constructs or other uglyties"
745
(defun my-python-mode-hook ()
746
;; setup preferred indentation style.
747
(setq fill-column 79)
748
(setq indent-tabs-mode nil) ; no tabs, never, I will not repeat
749
; (font-lock-add-keywords 'python-mode
750
; '(("^\\s *\t" . 'my-invalid-face) ; Leading tabs
751
; ("[ \t]+$" . 'my-invalid-face) ; Trailing spaces
752
; ("^[ \t]+$" . 'my-invalid-face)); Spaces only
756
(add-hook 'python-mode-hook 'my-python-mode-hook)
758
The lines beginning with ';' are comments. They can be activated
759
if one want to have a strong notice of some tab/space usage
483
__ http://www.python.org/peps/pep-0008.html
1416
1107
http://bazaar-vcs.org/BzrWin32Installer
1419
Core Developer Tasks
1420
####################
1425
What is a Core Developer?
1426
-------------------------
1428
While everyone in the Bazaar community is welcome and encouraged to
1429
propose and submit changes, a smaller team is reponsible for pulling those
1430
changes together into a cohesive whole. In addition to the general developer
1431
stuff covered above, "core" developers have responsibility for:
1434
* reviewing blueprints
1436
* managing releases.
1439
Removing barriers to community participation is a key reason for adopting
1440
distributed VCS technology. While DVCS removes many technical barriers,
1441
a small number of social barriers are often necessary instead.
1442
By documenting how the above things are done, we hope to
1443
encourage more people to participate in these activities, keeping the
1444
differences between core and non-core contributors to a minimum.
1447
The Development Lifecycle
1448
-------------------------
1450
As a rule, Bazaar development follows a 4 week cycle:
1452
* 2 weeks - general changes
1453
* 1 week - feature freeze
1454
* 1 week+ - Release Candidate stabilization
1456
During the FeatureFreeze week, the trunk (bzr.dev) is open in a limited
1457
way: only low risk changes, critical and high priority fixes are accepted
1458
during this time. At the end of FeatureFreeze, a branch is created for the
1459
first Release Candidate and the trunk is reopened for general development
1460
on the *next* release. A week or so later, the final release is packaged
1461
assuming no serious problems were encountered with the one or more Release
1465
There is a one week overlap between the start of one release and
1466
the end of the previous one.
1469
Communicating and Coordinating
1470
------------------------------
1472
While it has many advantages, one of the challenges of distributed
1473
development is keeping everyone else aware of what you're working on.
1474
There are numerous ways to do this:
1476
#. Assign bugs to yourself in Launchpad
1477
#. Mention it on the mailing list
1478
#. Mention it on IRC
1480
As well as the email notifcations that occur when merge requests are sent
1481
and reviewed, you can keep others informed of where you're spending your
1482
energy by emailing the **bazaar-commits** list implicitly. To do this,
1483
install and configure the Email plugin. One way to do this is add these
1484
configuration settings to your central configuration file (e.g.
1485
``~/.bazaar/bazaar.conf`` on Linux)::
1488
email = Joe Smith <joe.smith@internode.on.net>
1489
smtp_server = mail.internode.on.net:25
1491
Then add these lines for the relevant branches in ``locations.conf``::
1493
post_commit_to = bazaar-commits@lists.canonical.com
1494
post_commit_mailer = smtplib
1496
While attending a sprint, RobertCollins' Dbus plugin is useful for the
1497
same reason. See the documentation within the plugin for information on
1498
how to set it up and configure it.
1504
Setting Up Your Workspace for Reviews
1505
-------------------------------------
1507
TODO: Incorporate John Arbash Meinel's detailed email to Ian C on the
1508
numerous ways of setting up integration branches.
1511
The Review Checklist
1512
--------------------
1514
See `A Closer Look at the Merge & Review Process`_
1515
for information on the gates used to decide whether code can be merged
1516
or not and details on how review results are recorded and communicated.
1519
The Importance of Timely Reviews
1520
--------------------------------
1522
Good reviews do take time. They also regularly require a solid
1523
understanding of the overall code base. In practice, this means a small
1524
number of people often have a large review burden - with knowledge comes
1525
responsibility. No one like their merge requests sitting in a queue going
1526
nowhere, so reviewing sooner rather than later is strongly encouraged.
1535
Of the many workflows supported by Bazaar, the one adopted for Bazaar
1536
development itself is known as "Decentralized with automatic gatekeeper".
1537
To repeat the explanation of this given on
1538
http://bazaar-vcs.org/Workflows:
1541
In this workflow, each developer has their own branch or
1542
branches, plus read-only access to the mainline. A software gatekeeper
1543
(e.g. PQM) has commit rights to the main branch. When a developer wants
1544
their work merged, they request the gatekeeper to merge it. The gatekeeper
1545
does a merge, a compile, and runs the test suite. If the code passes, it
1546
is merged into the mainline.
1548
In a nutshell, here's the overall submission process:
1550
#. get your work ready (including review except for trivial changes)
1551
#. push to a public location
1552
#. ask PQM to merge from that location
1555
At present, PQM always takes the changes to merge from a branch
1556
at a URL that can be read by it. For Bazaar, that means a public,
1557
typically http, URL.
1559
As a result, the following things are needed to use PQM for submissions:
1561
#. A publicly available web server
1562
#. Your OpenPGP key registered with PQM (contact RobertCollins for this)
1563
#. The PQM plugin installed and configured (not strictly required but
1564
highly recommended).
1567
Selecting a Public Branch Location
1568
----------------------------------
1570
If you don't have your own web server running, branches can always be
1571
pushed to Launchpad. Here's the process for doing that:
1573
Depending on your location throughout the world and the size of your
1574
repository though, it is often quicker to use an alternative public
1575
location to Launchpad, particularly if you can set up your own repo and
1576
push into that. By using an existing repo, push only needs to send the
1577
changes, instead of the complete repository every time. Note that it is
1578
easy to register branches in other locations with Launchpad so no benefits
1579
are lost by going this way.
1582
For Canonical staff, http://people.ubuntu.com/~<user>/ is one
1583
suggestion for public http branches. Contact your manager for information
1584
on accessing this system if required.
1586
It should also be noted that best practice in this area is subject to
1587
change as things evolve. For example, once the Bazaar smart server on
1588
Launchpad supports server-side branching, the performance situation will
1589
be very different to what it is now (Jun 2007).
1592
Configuring the PQM Plug-In
1593
---------------------------
1595
While not strictly required, the PQM plugin automates a few things and
1596
reduces the chance of error. Before looking at the plugin, it helps to
1597
understand a little more how PQM operates. Basically, PQM requires an
1598
email indicating what you want it to do. The email typically looks like
1601
star-merge source-branch target-branch
1605
star-merge http://bzr.arbash-meinel.com/branches/bzr/jam-integration http://bazaar-vcs.org/bzr/bzr.dev
1607
Note that the command needs to be on one line. The subject of the email
1608
will be used for the commit message. The email also needs to be ``gpg``
1609
signed with a key that PQM accepts.
1611
The advantages of using the PQM plugin are:
1613
#. You can use the config policies to make it easy to set up public
1614
branches, so you don't have to ever type the full paths you want to merge
1617
#. It checks to make sure the public branch last revision matches the
1618
local last revision so you are submitting what you think you are.
1620
#. It uses the same public_branch and smtp sending settings as bzr-email,
1621
so if you have one set up, you have the other mostly set up.
1623
#. Thunderbird refuses to not wrap lines, and request lines are usually
1624
pretty long (you have 2 long URLs in there).
1626
Here are sample configuration settings for the PQM plugin. Here are the
1627
lines in bazaar.conf::
1630
email = Joe Smith <joe.smith@internode.on.net>
1631
smtp_server=mail.internode.on.net:25
1633
And here are the lines in ``locations.conf`` (or ``branch.conf`` for
1634
dirstate-tags branches)::
1636
[/home/joe/bzr/my-integration]
1637
push_location = sftp://joe-smith@bazaar.launchpad.net/%7Ejoe-smith/bzr/my-integration/
1638
push_location:policy = norecurse
1639
public_branch = http://bazaar.launchpad.net/~joe-smith/bzr/my-integration/
1640
public_branch:policy = appendpath
1641
pqm_email = Bazaar PQM <pqm@bazaar-vcs.org>
1642
pqm_branch = http://bazaar-vcs.org/bzr/bzr.dev
1644
Note that the push settings will be added by the first ``push`` on
1645
a branch. Indeed the preferred way to generate the lines above is to use
1646
``push`` with an argument, then copy-and-paste the other lines into
1653
Here is one possible recipe once the above environment is set up:
1655
#. pull bzr.dev => my-integration
1656
#. merge patch => my-integration
1657
#. fix up any final merge conflicts (NEWS being the big killer here).
1663
The ``push`` step is not required if ``my-integration`` is a checkout of
1666
Because of defaults, you can type a single message into commit and
1667
pqm-commit will reuse that.
1670
Tracking Change Acceptance
1671
--------------------------
1673
The web interface to PQM is https://pqm.bazaar-vcs.org/. After submitting
1674
a change, you can visit this URL to confirm it was received and placed in
1677
When PQM completes processing a change, an email is sent to you with the
1681
Reviewing Blueprints
1682
====================
1684
Blueprint Tracking Using Launchpad
1685
----------------------------------
1687
New features typically require a fair amount of discussion, design and
1688
debate. For Bazaar, that information is often captured in a so-called
1689
"blueprint" on our Wiki. Overall tracking of blueprints and their status
1690
is done using Launchpad's relevant tracker,
1691
https://blueprints.launchpad.net/bzr/. Once a blueprint for ready for
1692
review, please announce it on the mailing list.
1694
Alternatively, send an email begining with [RFC] with the proposal to the
1695
list. In some cases, you may wish to attach proposed code or a proposed
1696
developer document if that best communicates the idea. Debate can then
1697
proceed using the normal merge review processes.
1700
Recording Blueprint Review Feedback
1701
-----------------------------------
1703
Unlike its Bug Tracker, Launchpad's Blueprint Tracker doesn't currently
1704
(Jun 2007) support a chronological list of comment responses. Review
1705
feedback can either be recorded on the Wiki hosting the blueprints or by
1706
using Launchpad's whiteboard feature.
1715
As the two senior developers, Martin Pool and Robert Collins coordinate
1716
the overall Bazaar product development roadmap. Core developers provide
1717
input and review into this, particularly during sprints. It's totally
1718
expected that community members ought to be working on things that
1719
interest them the most. The roadmap is valuable though because it provides
1720
context for understanding where the product is going as a whole and why.
1723
Using Releases and Milestones in Launchpad
1724
------------------------------------------
1726
TODO ... (Exact policies still under discussion)
1732
Keeping on top of bugs reported is an important part of ongoing release
1733
planning. Everyone in the community is welcome and encouraged to raise
1734
bugs, confirm bugs raised by others, and nominate a priority. Practically
1735
though, a good percentage of bug triage is often done by the core
1736
developers, partially because of their depth of product knowledge.
1738
With respect to bug triage, core developers are encouraged to play an
1739
active role with particular attention to the following tasks:
1741
* keeping the number of unconfirmed bugs low
1742
* ensuring the priorities are generally right (everything as critical - or
1743
medium - is meaningless)
1744
* looking out for regressions and turning those around sooner rather than later.
1747
As well as prioritizing bugs and nominating them against a
1748
target milestone, Launchpad lets core developers offer to mentor others in
1758
TODO: Things to cover:
1760
* RFI on release objectives
1761
* RFI on higher risk things that are best done early, e.g. changes to file
1763
* Communication of proposed dates
1766
Weekly Status Updates
1767
---------------------
1769
TODO: Things to cover:
1771
* Early communication to downstream teams (e.g. Launchpad) about changes in dependencies.
1772
* Reminder re lifecycle and where we're up to right now
1773
* Summary of recent successes and pending work
1774
* Reminder re release objectives
1775
* Reminder re things needing attention, e.g. bug triage, reviews, testing of certain things, etc.
1781
TODO: Get material from http://bazaar-vcs.org/FeatureFreeze.
1787
TODO: Get material from http://bazaar-vcs.org/ReleaseChecklist and clean
1788
it up to make it clearer what the RC vs final vs both tasks are.
1794
TODO: Get material from http://bazaar-vcs.org/ReleaseChecklist and clean
1795
it up to make it clearer what the RC vs final vs both tasks are.
1798
1111
vim: ft=rst tw=74 ai
added
removed
doc/developers/HACKING
