/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to doc/developers/HACKING.txt

  • Committer: Jelmer Vernooij
  • Date: 2007-09-16 19:29:00 UTC
  • mfrom: (2823 +trunk)
  • mto: This revision was merged to the branch mainline in revision 2824.
  • Revision ID: jelmer@samba.org-20070916192900-fph1i2wsytberyyl
Merge bzr.dev.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/HACKING.txt
6
6
 
7
7
(The current version of this document is available in the file 
8
8
``doc/developers/HACKING.txt`` in the source tree, or at
9
 
http://doc.bazaar-vcs.org/bzr.dev/developers/HACKING.html)
 
9
http://doc.bazaar-vcs.org/bzr.dev/en/developer-guide/HACKING.html)
10
10
 
11
11
 
12
12
Getting Started
624
624
Coding Style Guidelines
625
625
=======================
626
626
 
 
627
Code layout
 
628
-----------
 
629
 
627
630
Please write PEP-8__ compliant code.  
628
631
 
 
632
__ http://www.python.org/peps/pep-0008.html
 
633
 
629
634
One often-missed requirement is that the first line of docstrings
630
635
should be a self-contained one-sentence summary.
631
636
 
632
 
__ http://www.python.org/peps/pep-0008.html
 
637
We use 4 space indents for blocks, and never use tab characters.  (In vim,
 
638
``set expandtab``.)
 
639
 
 
640
Lines should be no more than 79 characters if at all possible.
 
641
Lines that continue a long statement may be indented in either of 
 
642
two ways:
 
643
 
 
644
within the parenthesis or other character that opens the block, e.g.::
 
645
 
 
646
    my_long_method(arg1,
 
647
                   arg2,
 
648
                   arg3)
 
649
 
 
650
or indented by four spaces::
 
651
 
 
652
    my_long_method(arg1,
 
653
        arg2,
 
654
        arg3)
 
655
 
 
656
The first is considered clearer by some people; however it can be a bit
 
657
harder to maintain (e.g. when the method name changes), and it does not
 
658
work well if the relevant parenthesis is already far to the right.  Avoid
 
659
this::
 
660
 
 
661
     self.legbone.kneebone.shinbone.toebone.shake_it(one,
 
662
                                                     two,
 
663
                                                     three)
 
664
 
 
665
but rather ::
 
666
 
 
667
     self.legbone.kneebone.shinbone.toebone.shake_it(one,
 
668
         two,
 
669
         three)
 
670
 
 
671
or ::
 
672
 
 
673
     self.legbone.kneebone.shinbone.toebone.shake_it(
 
674
         one, two, three)
 
675
 
 
676
For long lists, we like to add a trailing comma and put the closing
 
677
character on the following line.  This makes it easier to add new items in
 
678
future::
 
679
 
 
680
    from bzrlib.goo import (
 
681
        jam,
 
682
        jelly,
 
683
        marmalade,
 
684
        )
 
685
 
 
686
There should be spaces between function paramaters, but not between the
 
687
keyword name and the value::
 
688
 
 
689
    call(1, 3, cheese=quark)
 
690
 
 
691
In emacs::
 
692
 
 
693
    ;(defface my-invalid-face
 
694
    ;  '((t (:background "Red" :underline t)))
 
695
    ;  "Face used to highlight invalid constructs or other uglyties"
 
696
    ;  )
 
697
 
 
698
    (defun my-python-mode-hook ()
 
699
     ;; setup preferred indentation style.
 
700
     (setq fill-column 79)
 
701
     (setq indent-tabs-mode nil) ; no tabs, never, I will not repeat
 
702
    ;  (font-lock-add-keywords 'python-mode
 
703
    ;                         '(("^\\s *\t" . 'my-invalid-face) ; Leading tabs
 
704
    ;                            ("[ \t]+$" . 'my-invalid-face)  ; Trailing spaces
 
705
    ;                            ("^[ \t]+$" . 'my-invalid-face)); Spaces only
 
706
    ;                          )
 
707
     )
 
708
 
 
709
    (add-hook 'python-mode-hook 'my-python-mode-hook)
 
710
 
 
711
The lines beginning with ';' are comments. They can be activated
 
712
if one want to have a strong notice of some tab/space usage
 
713
violations.
633
714
 
634
715
 
635
716
Module Imports
1287
1368
http://bazaar-vcs.org/BzrWin32Installer
1288
1369
 
1289
1370
 
 
1371
Core Developer Tasks
 
1372
####################
 
1373
 
 
1374
Overview
 
1375
========
 
1376
 
 
1377
What is a Core Developer?
 
1378
-------------------------
 
1379
 
 
1380
While everyone in the Bazaar community is welcome and encouraged to
 
1381
propose and submit changes, a smaller team is reponsible for pulling those
 
1382
changes together into a cohesive whole. In addition to the general developer
 
1383
stuff covered above, "core" developers have responsibility for:
 
1384
 
 
1385
* reviewing changes
 
1386
* reviewing blueprints
 
1387
* planning releases
 
1388
* managing releases.
 
1389
 
 
1390
.. note::
 
1391
  Removing barriers to community participation is a key reason for adopting
 
1392
  distributed VCS technology. While DVCS removes many technical barriers,
 
1393
  a small number of social barriers are often necessary instead.
 
1394
  By documenting how the above things are done, we hope to
 
1395
  encourage more people to participate in these activities, keeping the
 
1396
  differences between core and non-core contributors to a minimum.
 
1397
 
 
1398
 
 
1399
The Development Lifecycle
 
1400
-------------------------
 
1401
 
 
1402
As a rule, Bazaar development follows a 4 week cycle:
 
1403
 
 
1404
* 2 weeks - general changes
 
1405
* 1 week - feature freeze
 
1406
* 1 week+ - Release Candidate stabilization
 
1407
 
 
1408
During the FeatureFreeze week, the trunk (bzr.dev) is open in a limited
 
1409
way: only low risk changes, critical and high priority fixes are accepted
 
1410
during this time. At the end of FeatureFreeze, a branch is created for the
 
1411
first Release Candidate and the trunk is reopened for general development
 
1412
on the *next* release. A week or so later, the final release is packaged
 
1413
assuming no serious problems were encountered with the one or more Release
 
1414
Candidates.
 
1415
 
 
1416
.. note::
 
1417
  There is a one week overlap between the start of one release and
 
1418
  the end of the previous one.
 
1419
 
 
1420
 
 
1421
Communicating and Coordinating
 
1422
------------------------------
 
1423
 
 
1424
While it has many advantages, one of the challenges of distributed
 
1425
development is keeping everyone else aware of what you're working on.
 
1426
There are numerous ways to do this:
 
1427
 
 
1428
#. Assign bugs to yourself in Launchpad
 
1429
#. Mention it on the mailing list
 
1430
#. Mention it on IRC
 
1431
 
 
1432
As well as the email notifcations that occur when merge requests are sent
 
1433
and reviewed, you can keep others informed of where you're spending your
 
1434
energy by emailing the **bazaar-commits** list implicitly. To do this,
 
1435
install and configure the Email plugin. One way to do this is add these
 
1436
configuration settings to your central configuration file (e.g.
 
1437
``~/.bazaar/bazaar.conf`` on Linux)::
 
1438
 
 
1439
  [DEFAULT]
 
1440
  email = Joe Smith <joe.smith@internode.on.net>
 
1441
  smtp_server = mail.internode.on.net:25
 
1442
 
 
1443
Then add these lines for the relevant branches in ``locations.conf``::
 
1444
 
 
1445
  post_commit_to = bazaar-commits@lists.canonical.com
 
1446
  post_commit_mailer = smtplib
 
1447
 
 
1448
While attending a sprint, RobertCollins' Dbus plugin is useful for the
 
1449
same reason. See the documentation within the plugin for information on
 
1450
how to set it up and configure it.
 
1451
 
 
1452
 
 
1453
Reviewing Changes
 
1454
=================
 
1455
 
 
1456
Setting Up Your Workspace for Reviews
 
1457
-------------------------------------
 
1458
 
 
1459
TODO: Incorporate John Arbash Meinel's detailed email to Ian C on the
 
1460
numerous ways of setting up integration branches.
 
1461
 
 
1462
 
 
1463
The Review Checklist
 
1464
--------------------
 
1465
 
 
1466
See `A Closer Look at the Merge & Review Process`_
 
1467
for information on the gates used to decide whether code can be merged
 
1468
or not and details on how review results are recorded and communicated.
 
1469
 
 
1470
 
 
1471
The Importance of Timely Reviews
 
1472
--------------------------------
 
1473
 
 
1474
Good reviews do take time. They also regularly require a solid
 
1475
understanding of the overall code base. In practice, this means a small
 
1476
number of people often have a large review burden - with knowledge comes
 
1477
responsibility. No one like their merge requests sitting in a queue going
 
1478
nowhere, so reviewing sooner rather than later is strongly encouraged.
 
1479
 
 
1480
 
 
1481
Submitting Changes
 
1482
==================
 
1483
 
 
1484
An Overview of PQM
 
1485
------------------
 
1486
 
 
1487
Of the many workflows supported by Bazaar, the one adopted for Bazaar
 
1488
development itself is known as "Decentralized with automatic gatekeeper".
 
1489
To repeat the explanation of this given on
 
1490
http://bazaar-vcs.org/Workflows:
 
1491
 
 
1492
.. pull-quote::
 
1493
  In this workflow, each developer has their own branch or
 
1494
  branches, plus read-only access to the mainline. A software gatekeeper
 
1495
  (e.g. PQM) has commit rights to the main branch. When a developer wants
 
1496
  their work merged, they request the gatekeeper to merge it. The gatekeeper
 
1497
  does a merge, a compile, and runs the test suite. If the code passes, it
 
1498
  is merged into the mainline.
 
1499
 
 
1500
In a nutshell, here's the overall submission process:
 
1501
 
 
1502
#. get your work ready (including review except for trivial changes)
 
1503
#. push to a public location
 
1504
#. ask PQM to merge from that location
 
1505
 
 
1506
.. note::
 
1507
  At present, PQM always takes the changes to merge from a branch
 
1508
  at a URL that can be read by it. For Bazaar, that means a public,
 
1509
  typically http, URL.
 
1510
 
 
1511
As a result, the following things are needed to use PQM for submissions:
 
1512
 
 
1513
#. A publicly available web server
 
1514
#. Your OpenPGP key registered with PQM (contact RobertCollins for this)
 
1515
#. The PQM plugin installed and configured (not strictly required but
 
1516
   highly recommended).
 
1517
 
 
1518
 
 
1519
Selecting a Public Branch Location
 
1520
----------------------------------
 
1521
 
 
1522
If you don't have your own web server running, branches can always be
 
1523
pushed to Launchpad. Here's the process for doing that:
 
1524
 
 
1525
Depending on your location throughout the world and the size of your
 
1526
repository though, it is often quicker to use an alternative public
 
1527
location to Launchpad, particularly if you can set up your own repo and
 
1528
push into that. By using an existing repo, push only needs to send the
 
1529
changes, instead of the complete repository every time. Note that it is
 
1530
easy to register branches in other locations with Launchpad so no benefits
 
1531
are lost by going this way.
 
1532
 
 
1533
.. note::
 
1534
  For Canonical staff, http://people.ubuntu.com/~<user>/ is one
 
1535
  suggestion for public http branches. Contact your manager for information
 
1536
  on accessing this system if required.
 
1537
 
 
1538
It should also be noted that best practice in this area is subject to
 
1539
change as things evolve. For example, once the Bazaar smart server on
 
1540
Launchpad supports server-side branching, the performance situation will
 
1541
be very different to what it is now (Jun 2007).
 
1542
 
 
1543
 
 
1544
Configuring the PQM Plug-In
 
1545
---------------------------
 
1546
 
 
1547
While not strictly required, the PQM plugin automates a few things and
 
1548
reduces the chance of error. Before looking at the plugin, it helps to
 
1549
understand  a little more how PQM operates. Basically, PQM requires an
 
1550
email indicating what you want it to do. The email typically looks like
 
1551
this::
 
1552
 
 
1553
  star-merge source-branch target-branch
 
1554
 
 
1555
For example::
 
1556
 
 
1557
  star-merge http://bzr.arbash-meinel.com/branches/bzr/jam-integration http://bazaar-vcs.org/bzr/bzr.dev
 
1558
 
 
1559
Note that the command needs to be on one line. The subject of the email
 
1560
will be used for the commit message. The email also needs to be ``gpg``
 
1561
signed with a key that PQM accepts.
 
1562
 
 
1563
The advantages of using the PQM plugin are:
 
1564
 
 
1565
#. You can use the config policies to make it easy to set up public
 
1566
   branches, so you don't have to ever type the full paths you want to merge
 
1567
   from or into.
 
1568
 
 
1569
#. It checks to make sure the public branch last revision matches the
 
1570
   local last revision so you are submitting what you think you are.
 
1571
 
 
1572
#. It uses the same public_branch and smtp sending settings as bzr-email,
 
1573
   so if you have one set up, you have the other mostly set up.
 
1574
 
 
1575
#. Thunderbird refuses to not wrap lines, and request lines are usually
 
1576
   pretty long (you have 2 long URLs in there).
 
1577
 
 
1578
Here are sample configuration settings for the PQM plugin. Here are the
 
1579
lines in bazaar.conf::
 
1580
 
 
1581
  [DEFAULT]
 
1582
  email = Joe Smith <joe.smith@internode.on.net>
 
1583
  smtp_server=mail.internode.on.net:25
 
1584
 
 
1585
And here are the lines in ``locations.conf`` (or ``branch.conf`` for
 
1586
dirstate-tags branches)::
 
1587
 
 
1588
  [/home/joe/bzr/my-integration]
 
1589
  push_location = sftp://joe-smith@bazaar.launchpad.net/%7Ejoe-smith/bzr/my-integration/
 
1590
  push_location:policy = norecurse
 
1591
  public_branch = http://bazaar.launchpad.net/~joe-smith/bzr/my-integration/
 
1592
  public_branch:policy = appendpath
 
1593
  pqm_email = Bazaar PQM <pqm@bazaar-vcs.org>
 
1594
  pqm_branch = http://bazaar-vcs.org/bzr/bzr.dev
 
1595
 
 
1596
Note that the push settings will be added by the first ``push`` on
 
1597
a branch. Indeed the preferred way to generate the lines above is to use
 
1598
``push`` with an argument, then copy-and-paste the other lines into
 
1599
the relevant file.
 
1600
 
 
1601
 
 
1602
Submitting a Change
 
1603
-------------------
 
1604
 
 
1605
Here is one possible recipe once the above environment is set up:
 
1606
 
 
1607
#. pull bzr.dev => my-integration
 
1608
#. merge patch => my-integration
 
1609
#. fix up any final merge conflicts (NEWS being the big killer here).
 
1610
#. commit
 
1611
#. push
 
1612
#. pqm-submit
 
1613
 
 
1614
.. note::
 
1615
  The ``push`` step is not required if ``my-integration`` is a checkout of
 
1616
  a public branch.
 
1617
 
 
1618
  Because of defaults, you can type a single message into commit and
 
1619
  pqm-commit will reuse that.
 
1620
 
 
1621
 
 
1622
Tracking Change Acceptance
 
1623
--------------------------
 
1624
 
 
1625
The web interface to PQM is https://pqm.bazaar-vcs.org/. After submitting
 
1626
a change, you can visit this URL to confirm it was received and placed in
 
1627
PQM's queue.
 
1628
 
 
1629
When PQM completes processing a change, an email is sent to you with the
 
1630
results.
 
1631
 
 
1632
 
 
1633
Reviewing Blueprints
 
1634
====================
 
1635
 
 
1636
Blueprint Tracking Using Launchpad
 
1637
----------------------------------
 
1638
 
 
1639
New features typically require a fair amount of discussion, design and
 
1640
debate. For Bazaar, that information is often captured in a so-called
 
1641
"blueprint" on our Wiki. Overall tracking of blueprints and their status
 
1642
is done using Launchpad's relevant tracker,
 
1643
https://blueprints.launchpad.net/bzr/. Once a blueprint for ready for
 
1644
review, please announce it on the mailing list.
 
1645
 
 
1646
Alternatively, send an email begining with [RFC] with the proposal to the
 
1647
list. In some cases, you may wish to attach proposed code  or a proposed
 
1648
developer document if that best communicates the idea. Debate can then
 
1649
proceed using the normal merge review processes.
 
1650
 
 
1651
 
 
1652
Recording Blueprint Review Feedback
 
1653
-----------------------------------
 
1654
 
 
1655
Unlike its Bug Tracker, Launchpad's Blueprint Tracker doesn't currently
 
1656
(Jun 2007) support a chronological list of comment responses. Review
 
1657
feedback can either be recorded on the Wiki hosting the blueprints or by
 
1658
using Launchpad's whiteboard feature.
 
1659
 
 
1660
 
 
1661
Planning Releases
 
1662
=================
 
1663
 
 
1664
Roadmaps
 
1665
--------
 
1666
 
 
1667
As the two senior developers, Martin Pool and Robert Collins coordinate
 
1668
the overall Bazaar product development roadmap. Core developers provide
 
1669
input and review into this, particularly during sprints. It's totally
 
1670
expected that community members ought to be working on things that
 
1671
interest them the most. The roadmap is valuable though because it provides
 
1672
context for understanding where the product is going as a whole and why.
 
1673
 
 
1674
 
 
1675
Using Releases and Milestones in Launchpad
 
1676
------------------------------------------
 
1677
 
 
1678
TODO ... (Exact policies still under discussion)
 
1679
 
 
1680
 
 
1681
Bug Triage
 
1682
----------
 
1683
 
 
1684
Keeping on top of bugs reported is an important part of ongoing release
 
1685
planning. Everyone in the community is welcome and encouraged to raise
 
1686
bugs, confirm bugs raised by others, and nominate a priority. Practically
 
1687
though, a good percentage of bug triage is often done by the core
 
1688
developers, partially because of their depth of product knowledge.
 
1689
 
 
1690
With respect to bug triage, core developers are encouraged to play an
 
1691
active role with particular attention to the following tasks:
 
1692
 
 
1693
* keeping the number of unconfirmed bugs low
 
1694
* ensuring the priorities are generally right (everything as critical - or
 
1695
  medium - is meaningless)
 
1696
* looking out for regressions and turning those around sooner rather than later.
 
1697
 
 
1698
.. note::
 
1699
  As well as prioritizing bugs and nominating them against a
 
1700
  target milestone, Launchpad lets core developers offer to mentor others in
 
1701
  fixing them. Nice.
 
1702
 
 
1703
 
 
1704
Managing a Release
 
1705
==================
 
1706
 
 
1707
Starting a Release
 
1708
------------------
 
1709
 
 
1710
TODO: Things to cover:
 
1711
 
 
1712
* RFI on release objectives
 
1713
* RFI on higher risk things that are best done early, e.g. changes to file
 
1714
  format defaults
 
1715
* Communication of proposed dates
 
1716
 
 
1717
 
 
1718
Weekly Status Updates
 
1719
---------------------
 
1720
 
 
1721
TODO: Things to cover:
 
1722
 
 
1723
* Early communication to downstream teams (e.g. Launchpad) about changes in dependencies.
 
1724
* Reminder re lifecycle and where we're up to right now
 
1725
* Summary of recent successes and pending work
 
1726
* Reminder re release objectives
 
1727
* Reminder re things needing attention, e.g. bug triage, reviews, testing of certain things, etc.
 
1728
 
 
1729
 
 
1730
Feature Freeze
 
1731
--------------
 
1732
 
 
1733
TODO: Get material from http://bazaar-vcs.org/FeatureFreeze.
 
1734
 
 
1735
 
 
1736
Release Candidates
 
1737
------------------
 
1738
 
 
1739
TODO: Get material from http://bazaar-vcs.org/ReleaseChecklist and clean
 
1740
it up to make it clearer what the RC vs final vs both tasks are.
 
1741
 
 
1742
 
 
1743
The Final Release
 
1744
-----------------
 
1745
 
 
1746
TODO: Get material from http://bazaar-vcs.org/ReleaseChecklist and clean
 
1747
it up to make it clearer what the RC vs final vs both tasks are.
 
1748
 
1290
1749
..
1291
1750
   vim: ft=rst tw=74 ai