/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: Richard Wilbur
  • Date: 2016-02-04 19:07:28 UTC
  • mto: This revision was merged to the branch mainline in revision 6618.
  • Revision ID: richard.wilbur@gmail.com-20160204190728-p0zvfii6zase0fw7
Update COPYING.txt from the original http://www.gnu.org/licenses/gpl-2.0.txt  (Only differences were in whitespace.)  Thanks to Petr Stodulka for pointing out the discrepancy.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/HACKING.txt
1
1
======================
2
 
Breezy Developer Guide
 
2
Bazaar Developer Guide
3
3
======================
4
4
 
5
 
This document describes the Breezy internals and the development process.
6
 
It's meant for people interested in developing Breezy, and some parts will
7
 
also be useful to people developing Breezy plugins.
 
5
This document describes the Bazaar internals and the development process.
 
6
It's meant for people interested in developing Bazaar, and some parts will
 
7
also be useful to people developing Bazaar plugins.
8
8
 
9
9
If you have any questions or something seems to be incorrect, unclear or
10
10
missing, please talk to us in ``irc://irc.freenode.net/#bzr``, or write to
11
 
the Breezy mailing list.  To propose a correction or addition to this
 
11
the Bazaar mailing list.  To propose a correction or addition to this
12
12
document, send a merge request or new text to the mailing list.
13
13
 
14
14
The latest developer documentation can be found online at
15
 
https://www.breezy-vcs.org/developers/.
 
15
http://doc.bazaar.canonical.com/developers/.
16
16
 
17
17
Getting Started
18
18
###############
19
19
 
20
 
Exploring the Breezy Platform
 
20
Exploring the Bazaar Platform
21
21
=============================
22
22
 
23
23
Before making changes, it's a good idea to explore the work already
26
26
perhaps someone else has already fixed it?
27
27
 
28
28
To answer these questions and more, take a moment to explore the
29
 
overall Breezy Platform. Here are some links to browse:
 
29
overall Bazaar Platform. Here are some links to browse:
30
30
 
31
31
* The Plugins page on the Wiki - http://wiki.bazaar.canonical.com/BzrPlugins
32
32
 
33
 
* The Breezy product family on Launchpad - https://launchpad.net/breezy
 
33
* The Bazaar product family on Launchpad - https://launchpad.net/bazaar
34
34
 
35
 
* Bug Tracker for the core product - https://bugs.launchpad.net/brz/
 
35
* Bug Tracker for the core product - https://bugs.launchpad.net/bzr/
36
36
 
37
37
If nothing else, perhaps you'll find inspiration in how other developers
38
38
have solved their challenges.
41
41
=======================
42
42
 
43
43
Ad-hoc performance work can also be done. One useful tool is the 'evil' debug
44
 
flag. For instance running ``brz -Devil commit -m "test"`` will log a backtrace
45
 
to the Breezy log file for every method call which triggers a slow or non-scalable
46
 
part of the breezy library. So checking that a given command with ``-Devil`` has
 
44
flag. For instance running ``bzr -Devil commit -m "test"`` will log a backtrace
 
45
to the bzr log file for every method call which triggers a slow or non-scalable
 
46
part of the bzr library. So checking that a given command with ``-Devil`` has
47
47
no backtraces logged to the log file is a good way to find problem function
48
48
calls that might be nested deep in the code base.
49
49
 
50
50
Planning and Discussing Changes
51
51
===============================
52
52
 
53
 
There is a very active community around Breezy. Mostly we meet on IRC
54
 
(#bzr on irc.freenode.net) and on the mailing list. To join the Breezy
55
 
community, see https://www.breezy-vcs.org/pages/support.html.
 
53
There is a very active community around Bazaar. Mostly we meet on IRC
 
54
(#bzr on irc.freenode.net) and on the mailing list. To join the Bazaar
 
55
community, see http://wiki.bazaar.canonical.com/BzrSupport.
56
56
 
57
57
If you are planning to make a change, it's a very good idea to mention it
58
58
on the IRC channel and/or on the mailing list. There are many advantages
70
70
friendly, helpful and always keen to welcome newcomers.
71
71
 
72
72
 
73
 
Breezy Development in a Nutshell
 
73
Bazaar Development in a Nutshell
74
74
================================
75
75
 
76
76
.. was from http://wiki.bazaar.canonical.com/BzrGivingBack
77
77
 
78
 
One of the fun things about working on a version control system like Breezy is
 
78
One of the fun things about working on a version control system like Bazaar is
79
79
that the users have a high level of proficiency in contributing back into
80
80
the tool.  Consider the following very brief introduction to contributing back
81
 
to Breezy.  More detailed instructions are in the following sections.
 
81
to Bazaar.  More detailed instructions are in the following sections.
82
82
 
83
83
Making the change
84
84
-----------------
87
87
copy of bzr.dev?`_.)
88
88
::
89
89
 
90
 
 $ brz init-shared-repo ~/bzr
 
90
 $ bzr init-repo ~/bzr
91
91
 $ cd ~/bzr
92
 
 $ brz branch lp:brz bzr.dev
 
92
 $ bzr branch lp:bzr bzr.dev
93
93
 
94
94
Now make your own branch::
95
95
 
96
 
 $ brz branch bzr.dev 123456-my-bugfix
 
96
 $ bzr branch bzr.dev 123456-my-bugfix
97
97
 
98
98
This will give you a branch called "123456-my-bugfix" that you can work on
99
99
and commit in. Here, you can study the code, make a fix or a new feature.
100
100
Feel free to commit early and often (after all, it's your branch!).
101
101
 
102
102
Documentation improvements are an easy place to get started giving back to the
103
 
Breezy project.  The documentation is in the `doc/` subdirectory of the Breezy
 
103
Bazaar project.  The documentation is in the `doc/` subdirectory of the Bazaar
104
104
source tree.
105
105
 
106
106
When you are done, make sure that you commit your last set of changes as well!
110
110
Making a Merge Proposal
111
111
-----------------------
112
112
 
113
 
The Breezy developers use Launchpad to further enable a truly distributed
114
 
style of development.  Anyone can propose a branch for merging into the Breezy
 
113
The Bazaar developers use Launchpad to further enable a truly distributed
 
114
style of development.  Anyone can propose a branch for merging into the Bazaar
115
115
trunk.  To start this process, you need to push your branch to Launchpad.  To
116
116
do this, you will need a Launchpad account and user name, e.g.
117
117
`your_lp_username`.  You can push your branch to Launchpad directly from
118
 
Breezy::
 
118
Bazaar::
119
119
 
120
 
  $ brz push lp:~<your_lp_username>/bzr/meaningful_name_here
 
120
  $ bzr push lp:~<your_lp_username>/bzr/meaningful_name_here
121
121
 
122
122
After you have pushed your branch, you will need to propose it for merging to
123
 
the Breezy trunk.  Go to
 
123
the Bazaar trunk.  Go to
124
124
<https://launchpad.net/~<your_lp_username>/bzr/meaningful_name_here> and choose
125
125
"Propose for merging into another branch".  Select "lp:bzr" to hand
126
 
your changes off to the Breezy developers for review and merging.
 
126
your changes off to the Bazaar developers for review and merging.
127
127
 
128
 
Alternatively, after pushing you can use the ``propose`` command to
 
128
Alternatively, after pushing you can use the ``lp-propose`` command to 
129
129
create the merge proposal.
130
130
 
131
131
Using a meaningful name for your branch will help you and the reviewer(s)
164
164
 
165
165
Making a local mirror of bzr.dev is not strictly necessary, but it means
166
166
 
167
 
- You can use that copy of bzr.dev as your main brz executable, and keep it
168
 
  up-to-date using ``brz pull``.
 
167
- You can use that copy of bzr.dev as your main bzr executable, and keep it
 
168
  up-to-date using ``bzr pull``.
169
169
- Certain operations are faster, and can be done when offline.  For example:
170
170
 
171
 
  - ``brz bundle``
172
 
  - ``brz diff -r ancestor:...``
173
 
  - ``brz merge``
 
171
  - ``bzr bundle``
 
172
  - ``bzr diff -r ancestor:...``
 
173
  - ``bzr merge``
174
174
 
175
175
- When it's time to create your next branch, it's more convenient.  When you
176
176
  have further contributions to make, you should do them in their own branch::
177
177
 
178
178
    $ cd ~/bzr
179
 
    $ brz branch bzr.dev additional_fixes
 
179
    $ bzr branch bzr.dev additional_fixes
180
180
    $ cd additional_fixes # hack, hack, hack
181
181
 
182
182
 
201
201
 
202
202
* Launchpad - https://launchpad.net/
203
203
 
204
 
* Breezy - https://www.breezy-vcs.org/
 
204
* Bazaar - http://bazaar.canonical.com/
205
205
 
206
206
* Patch Queue Manager - https://launchpad.net/pqm/
207
207
 
208
 
For further information, see <https://www.breezy-vcs.org/developers/>.
209
 
 
210
 
 
211
 
Preparing a Sandbox for Making Changes to Breezy
 
208
For further information, see <http://wiki.bazaar.canonical.com/BzrDevelopment>.
 
209
 
 
210
 
 
211
 
 
212
 
 
213
Preparing a Sandbox for Making Changes to Bazaar
212
214
================================================
213
215
 
214
 
Breezy supports many ways of organising your work. See
 
216
Bazaar supports many ways of organising your work. See
215
217
http://wiki.bazaar.canonical.com/SharedRepositoryLayouts for a summary of the
216
218
popular alternatives.
217
219
 
222
224
* create a local copy of the main development branch (bzr.dev) by using
223
225
  this command::
224
226
 
225
 
    brz branch lp:brz bzr.dev
 
227
    bzr branch lp:bzr bzr.dev
226
228
 
227
229
* keep your copy of bzr.dev pristine (by not developing in it) and keep
228
 
  it up to date (by using brz pull)
 
230
  it up to date (by using bzr pull)
229
231
 
230
232
* create a new branch off your local bzr.dev copy for each issue
231
233
  (bug or feature) you are working on.
245
247
Some of the key files in this directory are:
246
248
 
247
249
bzr
248
 
    The command you run to start Breezy itself.  This script is pretty
 
250
    The command you run to start Bazaar itself.  This script is pretty
249
251
    short and just does some checks then jumps into bzrlib.
250
252
 
251
 
README.rst
252
 
    This file covers a brief introduction to Breezy and lists some of its
 
253
README
 
254
    This file covers a brief introduction to Bazaar and lists some of its
253
255
    key features.
254
256
 
255
257
setup.py
256
 
    Installs Breezy system-wide or to your home directory.  To perform
257
 
    development work on Breezy it is not required to run this file - you
258
 
    can simply run the Breezy command from the top level directory of your
 
258
    Installs Bazaar system-wide or to your home directory.  To perform
 
259
    development work on Bazaar it is not required to run this file - you
 
260
    can simply run the bzr command from the top level directory of your
259
261
    development copy. Note: That if you run setup.py this will create a
260
262
    'build' directory in your development branch. There's nothing wrong
261
263
    with this but don't be confused by it. The build process puts a copy
266
268
bzrlib
267
269
    Possibly the most exciting folder of all, bzrlib holds the main code
268
270
    base. This is where you will go to edit python files and contribute to
269
 
    Breezy.
 
271
    Bazaar.
270
272
 
271
273
doc
272
 
    Holds documentation on a whole range of things on Breezy from the
273
 
    origination of ideas within the project to information on Breezy
 
274
    Holds documentation on a whole range of things on Bazaar from the
 
275
    origination of ideas within the project to information on Bazaar
274
276
    features and use cases.  Within this directory there is a subdirectory
275
277
    for each translation into a human language.  All the documentation
276
278
    is in the ReStructuredText markup language.
277
279
 
278
280
doc/developers
279
 
    Documentation specifically targeted at Breezy and plugin developers.
 
281
    Documentation specifically targeted at Bazaar and plugin developers.
280
282
    (Including this document.)
281
283
 
282
284
doc/en/release-notes/
283
285
 
284
 
    Detailed changes in each Breezy release (there is one file by series:
 
286
    Detailed changes in each Bazaar release (there is one file by series:
285
287
    bzr-2.3.txt, bzr-2.4.txt, etc) that can affect users or plugin
286
288
    developers.
287
289
 
288
290
doc/en/whats-new/
289
291
 
290
 
    High-level summaries of changes in each Breezy release (there is one
 
292
    High-level summaries of changes in each Bazaar release (there is one
291
293
    file by series: whats-new-in-2.3.txt, whats-new-in-2.4.txt, etc).
292
294
 
293
295
 
294
296
Automatically-generated API reference information is available at
295
 
<https://www.breezy-vcs.org/developers/api/>.
 
297
<http://people.canonical.com/~mwh/bzrlibapi/>.
296
298
 
297
 
See also the `Breezy Architectural Overview
298
 
<https://www.breezy-vcs.org/developers/overview.html>`_.
 
299
See also the `Bazaar Architectural Overview
 
300
<http://doc.bazaar.canonical.com/developers/overview.html>`_.
299
301
 
300
302
 
301
303
Core Topics
305
307
===================
306
308
 
307
309
We don't change APIs in stable branches: any supported symbol in a stable
308
 
release of Breezy must not be altered in any way that would result in
 
310
release of bzr must not be altered in any way that would result in
309
311
breaking existing code that uses it. That means that method names,
310
312
parameter ordering, parameter names, variable and attribute names etc must
311
313
not be changed without leaving a 'deprecated forwarder' behind. This even
366
368
General Guidelines
367
369
==================
368
370
 
 
371
Copyright
 
372
---------
 
373
 
 
374
The copyright policy for bzr was recently made clear in this email (edited
 
375
for grammatical correctness)::
 
376
 
 
377
    The attached patch cleans up the copyright and license statements in
 
378
    the bzr source. It also adds tests to help us remember to add them
 
379
    with the correct text.
 
380
 
 
381
    We had the problem that lots of our files were "Copyright Canonical
 
382
    Development Ltd" which is not a real company, and some other variations
 
383
    on this theme. Also, some files were missing the GPL statements.
 
384
 
 
385
    I want to be clear about the intent of this patch, since copyright can
 
386
    be a little controversial.
 
387
 
 
388
    1) The big motivation for this is not to shut out the community, but
 
389
    just to clean up all of the invalid copyright statements.
 
390
 
 
391
    2) It has been the general policy for bzr that we want a single
 
392
    copyright holder for all of the core code. This is following the model
 
393
    set by the FSF, which makes it easier to update the code to a new
 
394
    license in case problems are encountered. (For example, if we want to
 
395
    upgrade the project universally to GPL v3 it is much simpler if there is
 
396
    a single copyright holder). It also makes it clearer if copyright is
 
397
    ever debated, there is a single holder, which makes it easier to defend
 
398
    in court, etc. (I think the FSF position is that if you assign them
 
399
    copyright, they can defend it in court rather than you needing to, and
 
400
    I'm sure Canonical would do the same).
 
401
    As such, Canonical has requested copyright assignments from all of the
 
402
    major contributers.
 
403
 
 
404
    3) If someone wants to add code and not attribute it to Canonical, there
 
405
    is a specific list of files that are excluded from this check. And the
 
406
    test failure indicates where that is, and how to update it.
 
407
 
 
408
    4) If anyone feels that I changed a copyright statement incorrectly, just
 
409
    let me know, and I'll be happy to correct it. Whenever you have large
 
410
    mechanical changes like this, it is possible to make some mistakes.
 
411
 
 
412
    Just to reiterate, this is a community project, and it is meant to stay
 
413
    that way. Core bzr code is copyright Canonical for legal reasons, and
 
414
    the tests are just there to help us maintain that.
 
415
 
 
416
 
369
417
Miscellaneous Topics
370
418
####################
371
419
 
372
420
Debugging
373
421
=========
374
422
 
375
 
Breezy has a few facilities to help debug problems by going into pdb_, the
 
423
Bazaar has a few facilities to help debug problems by going into pdb_, the
376
424
Python debugger.
377
425
 
378
426
.. _pdb: http://docs.python.org/lib/debugger-commands.html
379
427
 
380
428
If the ``BZR_PDB`` environment variable is set
381
 
then brz will go into pdb post-mortem mode when an unhandled exception
 
429
then bzr will go into pdb post-mortem mode when an unhandled exception
382
430
occurs.
383
431
 
384
 
If you send a SIGQUIT or SIGBREAK signal to brz then it will drop into the
 
432
If you send a SIGQUIT or SIGBREAK signal to bzr then it will drop into the
385
433
debugger immediately. SIGQUIT can be generated by pressing Ctrl-\\ on
386
434
Unix.  SIGBREAK is generated with Ctrl-Pause on Windows (some laptops have
387
435
this as Fn-Pause).  You can continue execution by typing ``c``.  This can
398
446
Debug Flags
399
447
===========
400
448
 
401
 
Breezy accepts some global options starting with ``-D`` such as
 
449
Bazaar accepts some global options starting with ``-D`` such as
402
450
``-Dhpss``.  These set a value in `bzrlib.debug.debug_flags`, and
403
451
typically cause more information to be written to the trace file.  Most
404
452
`mutter` calls should be guarded by a check of those flags so that we
406
454
 
407
455
Debug flags may have effects other than just emitting trace messages.
408
456
 
409
 
Run ``brz help global-options`` to see them all.
 
457
Run ``bzr help global-options`` to see them all.
410
458
 
411
459
These flags may also be set as a comma-separated list in the
412
 
``debug_flags`` option in e.g.  ``~/.config/breezy/breezy.conf``.  (Note
413
 
that it must be in this global file, not in the branch or location
414
 
configuration, because it's currently only loaded at startup time.)  For
415
 
instance you may want to always record hpss traces and to see full error
416
 
tracebacks::
 
460
``debug_flags`` option in e.g.  ``~/.bazaar/bazaar.conf``.  (Note that it
 
461
must be in this global file, not in the branch or location configuration,
 
462
because it's currently only loaded at startup time.)  For instance you may
 
463
want to always record hpss traces and to see full error tracebacks::
417
464
 
418
465
    debug_flags = hpss, error
419
466
 
430
477
Unicode and Encoding Support
431
478
============================
432
479
 
433
 
This section discusses various techniques that Breezy uses to handle
 
480
This section discusses various techniques that Bazaar uses to handle
434
481
characters that are outside the ASCII set.
435
482
 
436
483
``Command.outf``
450
497
    marker (typically '?'), and no exception will be raised. This is for
451
498
    any command which generates text for the user to review, rather than
452
499
    for automated processing.
453
 
    For example: ``brz log`` should not fail if one of the entries has text
 
500
    For example: ``bzr log`` should not fail if one of the entries has text
454
501
    that cannot be displayed.
455
502
 
456
503
  strict
457
504
    Attempting to print an unprintable character will cause a UnicodeError.
458
505
    This is for commands that are intended more as scripting support, rather
459
506
    than plain user review.
460
 
    For example: ``brz ls`` is designed to be used with shell scripting. One
461
 
    use would be ``brz ls --null --unknowns | xargs -0 rm``.  If ``bzr``
 
507
    For example: ``bzr ls`` is designed to be used with shell scripting. One
 
508
    use would be ``bzr ls --null --unknowns | xargs -0 rm``.  If ``bzr``
462
509
    printed a filename with a '?', the wrong file could be deleted. (At the
463
510
    very least, the correct file would not be deleted). An error is used to
464
511
    indicate that the requested action could not be performed.
466
513
  exact
467
514
    Do not attempt to automatically convert Unicode strings. This is used
468
515
    for commands that must handle conversion themselves.
469
 
    For example: ``brz diff`` needs to translate Unicode paths, but should
 
516
    For example: ``bzr diff`` needs to translate Unicode paths, but should
470
517
    not change the exact text of the contents of the files.
471
518
 
472
519
 
485
532
C Extension Modules
486
533
===================
487
534
 
488
 
We write some extensions in C using Cython. We design these to work in
 
535
We write some extensions in C using pyrex. We design these to work in
489
536
three scenarios:
490
537
 
491
538
 * User with no C compiler
492
539
 * User with C compiler
493
540
 * Developers
494
541
 
495
 
The recommended way to install Breezy is to have a C compiler so that the
 
542
The recommended way to install bzr is to have a C compiler so that the
496
543
extensions can be built, but if no C compiler is present, the pure python
497
544
versions we supply will work, though more slowly.
498
545
 
499
 
For developers we recommend that Cython be installed, so that the C
 
546
For developers we recommend that pyrex be installed, so that the C
500
547
extensions can be changed if needed.
501
548
 
502
549
For the C extensions, the extension module should always match the
503
550
original python one in all respects (modulo speed). This should be
504
551
maintained over time.
505
552
 
506
 
To create an extension, add rules to setup.py for building it with Cython ,
 
553
To create an extension, add rules to setup.py for building it with pyrex,
507
554
and with distutils. Now start with an empty .pyx file. At the top add
508
555
"include 'yourmodule.py'". This will import the contents of foo.py into this
509
556
file at build time - remember that only one module will be loaded at
510
557
runtime. Now you can subclass classes, or replace functions, and only your
511
558
changes need to be present in the .pyx file.
512
559
 
 
560
Note that pyrex does not support all 2.4 programming idioms, so some
 
561
syntax changes may be required. I.e.
 
562
 
 
563
 - 'from foo import (bar, gam)' needs to change to not use the brackets.
 
564
 - 'import foo.bar as bar' needs to be 'import foo.bar; bar = foo.bar'
 
565
 
 
566
If the changes are too dramatic, consider
 
567
maintaining the python code twice - once in the .pyx, and once in the .py,
 
568
and no longer including the .py file.
 
569
 
 
570
 
513
571
Making Installers for OS Windows
514
572
================================
515
573
To build a win32 installer, see the instructions on the wiki page:
524
582
What is a Core Developer?
525
583
-------------------------
526
584
 
527
 
While everyone in the Breezy community is welcome and encouraged to
 
585
While everyone in the Bazaar community is welcome and encouraged to
528
586
propose and submit changes, a smaller team is reponsible for pulling those
529
587
changes together into a cohesive whole. In addition to the general developer
530
588
stuff covered above, "core" developers have responsibility for:
531
589
 
532
590
* reviewing changes
533
591
* planning releases
534
 
* managing releases (see `Releasing Breezy <https://www.breezy-vcs.org/developers/releasing.html>`_)
 
592
* managing releases (see `Releasing Bazaar <http://doc.bazaar.canonical.com/developers/releasing.html>`_)
535
593
 
536
594
.. note::
537
595
  Removing barriers to community participation is a key reason for adopting
558
616
energy by emailing the **bazaar-commits** list implicitly. To do this,
559
617
install and configure the Email plugin. One way to do this is add these
560
618
configuration settings to your central configuration file (e.g.
561
 
``~/.config/breezy/breezy.conf``)::
 
619
``~/.bazaar/bazaar.conf``)::
562
620
 
563
621
  [DEFAULT]
564
622
  email = Joe Smith <joe.smith@internode.on.net>