Merge lp:~jelmer/brz/yet-more-docs into lp:brz

Proposed by Jelmer Vernooij
Status: Merged
Approved by: Jelmer Vernooij
Approved revision: no longer in the source branch.
Merge reported by: The Breezy Bot
Merged at revision: not available
Proposed branch: lp:~jelmer/brz/yet-more-docs
Merge into: lp:brz
Diff against target: 415 lines (+275/-44)
8 files modified
doc/developers/index-plain.txt (+2/-2)
doc/developers/index.txt (+1/-1)
doc/developers/plugin-api.txt (+2/-2)
doc/developers/plugin-development.txt (+264/-0)
doc/en/_templates/index.html (+2/-2)
doc/en/tutorials/using_breezy_with_launchpad.txt (+0/-33)
doc/en/user-guide/hooks.txt (+1/-1)
doc/en/user-guide/writing_a_plugin.txt (+3/-3)
To merge this branch: bzr merge lp:~jelmer/brz/yet-more-docs
Reviewer Review Type Date Requested Status
Martin Packman Approve
Review via email: mp+359087@code.launchpad.net

Commit message

Some more minor improvements to the docs.

Description of the change

Some more minor improvements to the docs:

 * Fix links to glossary and developer docs
 * Drop canonical-specific blurb from Launchpad tutorial

To post a comment you must log in.
Revision history for this message
Martin Packman (gz) wrote :

Thanks! Am aware this is mostly ported over text, but have left some inline comments for things that seem not quite right.

review: Approve

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'doc/developers/index-plain.txt'
2--- doc/developers/index-plain.txt 2018-11-18 14:23:08 +0000
3+++ doc/developers/index-plain.txt 2018-11-22 02:24:44 +0000
4@@ -28,8 +28,8 @@
5
6 * `Breezy Code Style Guide <code-style.html>`_.
7
8-* `Writing plugins <http://doc.bazaar.canonical.com/plugins/en/plugin-development.html>`_
9- |--| specific advice on writing Breezy plugins. (web link)
10+* `Writing plugins <plugin-development.html>`_
11+ |--| specific advice on writing Breezy plugins.
12
13 * `Documenting changes <documenting-changes.html>`_.
14
15
16=== modified file 'doc/developers/index.txt'
17--- doc/developers/index.txt 2018-11-18 14:23:08 +0000
18+++ doc/developers/index.txt 2018-11-22 02:24:44 +0000
19@@ -60,7 +60,7 @@
20 overview
21 integration
22
23-* `Writing plugins for Breezy <http://doc.bazaar.canonical.com/plugins/en/plugin-development.html>`_ (web link)
24+* `Writing plugins for Breezy <plugin-development.txt>`_
25
26 * `breezy API reference <api/index.txt>`_
27
28
29=== modified file 'doc/developers/plugin-api.txt'
30--- doc/developers/plugin-api.txt 2018-11-18 18:23:32 +0000
31+++ doc/developers/plugin-api.txt 2018-11-22 02:24:44 +0000
32@@ -23,7 +23,7 @@
33 --------
34
35 * `Breezy Developer Documentation Catalog <../index.html>`_.
36- * `Breezy Plugins Guide <http://doc.bazaar.canonical.com/plugins/en/plugin-development.html>`_ for
37+ * `Breezy Plugins Guide <plugin-development.txt>`_ for
38 more suggestions about particular APIs.
39
40
41@@ -241,7 +241,7 @@
42 time other than register or override functions to be called later.
43
44 The plugin can import breezy and call any function.
45-Some interesting APIs are described in `Breezy Plugins Guide <http://doc.bazaar.canonical.com/plugins/en/plugin-development.html>`_.
46+Some interesting APIs are described in `Breezy Plugins Guide <plugin-development.txt>`_.
47
48
49 Publishing your plugin
50
51=== added file 'doc/developers/plugin-development.txt'
52--- doc/developers/plugin-development.txt 1970-01-01 00:00:00 +0000
53+++ doc/developers/plugin-development.txt 2018-11-22 02:24:44 +0000
54@@ -0,0 +1,264 @@
55+Developing a plugin
56+===================
57+
58+Naming
59+------
60+
61+By convention, most plugins are named brz-xxx and are installed into a
62+directory called xxx. Note that the directory name must be a legal
63+Python package name, so a plugin called brz-xxx-yyy need to be installed
64+into a directory called xxx_yyy, i.e. '-' in a plugin name should be mapped to
65+an underscore in the directory name.
66+
67+
68+Licensing
69+---------
70+
71+We encourage plugin authors to make their plugins publicly available
72+under the same license as Breezy itself, namely GPL v2 or later. However, there
73+is no requirement to do so. You are free to create Breezy plugins for
74+private or internal use within your company and not distribute them.
75+
76+By sharing your work, a larger number of people benefit. In our experience,
77+plugin developers also benefit heavily by having more users involved in
78+the design, testing, bug fixing and longer term maintenance. In other words,
79+sharing leads to a better plugin faster.
80+
81+
82+Testing
83+-------
84+
85+To ensure your plugin under development is available to Breezy, set
86+the ``BRZ_PLUGIN_PATH`` environment variable to its parent directory.
87+Alternatively, you may wish to develop your plugin within a directory
88+under your personal plugins area (``~/.bazaar/plugins`` on GNU/Linux)
89+or put a symbolic link in that area pointing to your plugin under
90+test. Finally you can use ``BRZ_PLUGINS_AT`` to point to a specific
91+directory for a specific plugin (separated by your platform's value of
92+os.pathsep), e.g.
93+
94+ export BRZ_PLUGINS_AT=qbrz@/home/me/qbrz:explorer@/home/me/explorer
95+
96+You can disable loading plugins with ``BRZ_DISABLE_PLUGINS``.
97+
98+If you want to stop loading all but installed plugins you can use:
99+
100+ BRZ_PLUGIN_PATH=-site
101+
102+We also encourage plugin developers to provide tests for their plugin.
103+When you run ``brz selftest``, Breezy will scan all its plugins to see if
104+they contain a function named ``test_suite()``. For each plugin that does,
105+it calls the function and adds any resulting tests to the master test suite.
106+To run just the tests for plugin xxx, the command is::
107+
108+ brz selftest -s bp.xxx
109+
110+
111+Providing help
112+--------------
113+
114+Plugins in this guide have their documentation automatically
115+generated from the online help provided for a plugin. Sections are
116+ordered as follows:
117+
118+1. High level introduction
119+2. Plugin-specific help topics (COMING SOON)
120+3. Commands defined or extended by the plugin.
121+
122+High level help is specified in the docstring for the ``__init__.py`` module.
123+You can register plugin-specific help topics in ``__init__.py`` like this::
124+
125+ _xxx_tutorial = """XXX Tutorial
126+
127+ Welcome to xxx, your new best friend. ...
128+ """
129+ topic_registry.register('xxx-tutorial',
130+ _xxx_tutorial,
131+ 'How to use xxx')
132+
133+Command level help is specified in the docstring for the relevant
134+``cmd_xxx`` Command class.
135+
136+.. note::
137+
138+ The final documentation needs to be in ReST format. Keep in mind though
139+ that the documentation should also be readable via ``brz help xxx`` so
140+ it's best to keep markup to a reasonable minimum.
141+
142+
143+Providing custom code via hooks
144+-------------------------------
145+
146+Hooks let you provide custom code at certain processing points.
147+The available hook point are documented in the `User Reference
148+<http://doc.bazaar-vcs.org/development/en/user-reference/index.html#hooks>`_.
149+
150+Adding a new hook is done with, for example::
151+
152+ import breezy.branch
153+ breezy.branch.Branch.hooks.install_named_hook('post_push', post_push_hook,
154+ 'My post_push hook')
155+
156+For more information on how to write hooks,
157+see http://doc.bazaar-vcs.org/development/en/user-guide/hooks.html.
158+
159+
160+Defining a new command
161+----------------------
162+
163+Breezy commands are defined as subclasses of ``breezy.commands.Command``, the
164+command name is specified by the name of the subclass, and they must be
165+registered into ``brz`` with the ``breezy.commands.register_command`` function
166+at module import time.
167+
168+To define the ``brz foo-bar`` command::
169+
170+ from breezy.commands import Command, register_command
171+
172+ class cmd_foo_bar(Command):
173+ # see breezy/builtins.py for information about what to put here
174+ pass
175+
176+ register_command(cmd_foo_bar)
177+
178+If the class name starts with ``cmd_``, the prefix will get dropped
179+and ``_`` will be replaced by ``-`` characters.
180+
181+
182+Managing data
183+-------------
184+
185+Plugin data falls into several categories:
186+
187+* Configuration settings.
188+* Data the user can see and version control.
189+* Data behind the scenes.
190+
191+Configuration settings are often stored in ``branch.conf``,
192+``locations.conf`` or ``bazaar.conf``.
193+
194+User-visible data for a plugin called xxx should be stored in
195+``.bzrmeta/xxx``. If mutiple files are desirable, make ``.bzrmeta/xxx``
196+a directory or give them a common prefix within ``.bzrmeta``, e.g.
197+``xxx-foo``, ``xxx-bar``.
198+
199+Data managed behind the scenes should be stored in ``.bzr``.
200+Depending on the nature of the data, it may belong in a subdirectory
201+within there, e.g. ``checkout``, ``branch`` or ``repository``.
202+It's your responsibility to ensure behind-the-scenes data is
203+propagated and merged appropriately via custom code. You may want
204+to use existing hooks for this or ask for new hooks to help.
205+
206+Useful metadata
207+---------------
208+
209+It is highly recommended that plugins define a version number. This
210+is displayed by ``brz plugins`` and by the ``qplugins`` GUI dialog.
211+To do this, define ``version_info`` in ``__init__.py`` like this::
212+
213+ version_info = (1, 2, 0, 'beta', 1)
214+
215+Plugins can also declare other useful metadata such as a mimimum
216+breezy version, new transports and storage formats. See
217+`Plugin API <plugin-api>`_ for details.
218+
219+
220+Performance tips
221+----------------
222+
223+When brz starts up, it imports every plugin, so plugins can degrade
224+performance when they're not being used. However, sub-modules are not
225+loaded, only the main name.
226+
227+One way you can avoid this slowdown is by putting most of your code
228+in sub-modules, so that the plugin, itself, is small. All you really
229+need in the ``__init__.py`` is the plugin's Command classes, the
230+commands to register them, and the optional ``test_suite()``.
231+
232+Another way to reduce your plugin's overhead is to use the breezy
233+lazy_import functionality. That looks something like this::
234+
235+ from breezy.lazy_import import lazy_import
236+ lazy_import(globals(), """
237+ from breezy import (
238+ branch as _mod_branch,
239+ option,
240+ workingtree,
241+ )
242+ """)
243+
244+Lazy importing only works for packages and modules, not classes or
245+functions. It defers the import until you actually need it.
246+
247+
248+Learning more
249+-------------
250+
251+`Integrating with Bazaar <http://wiki.bazaar.canonical.com/Integrating_with_Bazaar>`_
252+explains how to do such operations as ``add``, ``commit``, ``log`` and more.
253+
254+Reference documentation on some key APIs is provided below. For a more
255+detailed reference, see the `complete breezy API documentation <api/index>`_.
256+
257+
258+Mini API Reference
259+------------------
260+
261+Command Class
262+~~~~~~~~~~~~~
263+
264+Base class for commands. Commands are the heart of the command-line brz
265+interface.
266+
267+The command object mostly handles the mapping of command-line parameters into
268+one or more breezy operations, and of the results into textual output.
269+
270+Commands normally don't have any state. All their arguments are passed in to
271+the run method. (Subclasses may take a different policy if the behaviour of the
272+instance needs to depend on e.g. a shell plugin and not just its Python class.)
273+
274+The docstring for an actual command should give a single-line summary, then a
275+complete description of the command. A grammar description will be inserted.
276+
277+aliases
278+ Other accepted names for this command.
279+
280+takes_args
281+ List of argument forms, marked with whether they are optional,
282+ repeated, etc.
283+
284+ For example: ``['to_location', 'from_branch?', 'file*']`` means:
285+
286+ * 'to_location' is required
287+ * 'from_branch' is optional
288+ * 'file' can be specified 0 or more times
289+
290+takes_options
291+ List of options that may be given for this command. These can be either
292+ strings, referring to globally-defined options, or option objects.
293+ Retrieve through options().
294+
295+hidden
296+ If true, this command isn't advertised. This is typically for commands
297+ intended for expert users.
298+
299+run()
300+ Actually run the command. This is invoked with the options and arguments
301+ bound to keyword parameters.
302+
303+ Return 0 or None if the command was successful, or a non-zero shell error
304+ code if not. It's OK for this method to allow an exception to raise up.
305+
306+
307+register_command Function
308+~~~~~~~~~~~~~~~~~~~~~~~~~
309+
310+Utility function to help register a command.
311+
312+param *cmd*
313+ Command subclass to register
314+
315+param *decorate*
316+ If true, allow overriding an existing command of the same name; the old
317+ command is returned by this function. Otherwise it is an error to try to
318+ override an existing command.
319
320=== modified file 'doc/en/_templates/index.html'
321--- doc/en/_templates/index.html 2018-11-18 13:17:18 +0000
322+++ doc/en/_templates/index.html 2018-11-22 02:24:44 +0000
323@@ -45,12 +45,12 @@
324 <p class="biglink"><a class="biglink" href="https://answers.launchpad.net/brz/+faqs">FAQ</a><br/>
325 <span class="linkdescr">frequently asked questions</span>
326 </p>
327- <p class="biglink"><a class="biglink" href="http://wiki.bazaar.canonical.com/brzGlossary/">Glossary</a><br/>
328+ <p class="biglink"><a class="biglink" href="user-reference/glossary-help.html">Glossary</a><br/>
329 <span class="linkdescr">help with terminology</span>
330 </p>
331 </td>
332 <td width="50%">
333- <p class="biglink"><a class="biglink" href="../developers/">Developer Docs</a><br/>
334+ <p class="biglink"><a class="biglink" href="{{ pathto("developers/index") }}">Developer Docs</a><br/>
335 <span class="linkdescr">improving and extending brz</span>
336 </p>
337 <p class="biglink"><a class="biglink" href="http://doc.bazaar.canonical.com/migration/en/">Migration Docs</a><br/>
338
339=== modified file 'doc/en/tutorials/using_breezy_with_launchpad.txt'
340--- doc/en/tutorials/using_breezy_with_launchpad.txt 2018-11-18 13:16:09 +0000
341+++ doc/en/tutorials/using_breezy_with_launchpad.txt 2018-11-22 02:24:44 +0000
342@@ -410,36 +410,3 @@
343 library of 750,000 translated strings, and a community of 19,000
344 registered translators can radically cut the time required to
345 localise your project into many languages.
346-
347-
348-Summary
349-=======
350-
351-The communities we join, whether off-line or on-line,
352-say a lot about the sort of people we are. The flip-side
353-to this is that the tools you choose for your community - particularly
354-the CDE and version control tool - can have a large impact on who
355-joins and how easily they can contribute.
356-
357-In their own right, Launchpad and Breezy are highly useful tools.
358-Together, they can:
359-
360-* help your community track major assets such as source code and knowledge
361-* help it grow by reducing barriers to entry
362-* help it interact with related communities.
363-
364-In particular, Launchpad is a free code hosting service for your Breezy
365-branches, branches can be browsed online, branches can be linked to bugs
366-and blueprints, and the status of bug-branch relationships can be
367-automatically managed by mentioning the bug while committing in Breezy.
368-Further integration is under development with the aim of streamlining
369-the process from *great idea* to *running code in the hands of end users*.
370-
371-If you have any feedback on how you'd like to see Breezy and Launchpad
372-further integrated, please contact us on the Bazaar mailing list,
373-bazaar@lists.canonical.com.
374-
375-While designed as a free service to support free software projects,
376-Canonical may make Launchpad available to commercial software developers
377-depending on their requirements. We would be happy to hear from you
378-if you think Launchpad would be useful for managing your community.
379
380=== modified file 'doc/en/user-guide/hooks.txt'
381--- doc/en/user-guide/hooks.txt 2017-05-21 18:10:28 +0000
382+++ doc/en/user-guide/hooks.txt 2018-11-22 02:24:44 +0000
383@@ -33,7 +33,7 @@
384 branch.Branch.hooks.install_named_hook('post_push', post_push_hook,
385 'My post_push hook')
386
387-.. _write a plugin: http://doc.bazaar.canonical.com/plugins/en/plugin-development.html
388+.. _write a plugin: ../../developers/plugin-development.html
389
390 To use this example, create a file named ``push_hook.py``, and stick it in
391 ``plugins`` subdirectory of your configuration directory. (If you have never
392
393=== modified file 'doc/en/user-guide/writing_a_plugin.txt'
394--- doc/en/user-guide/writing_a_plugin.txt 2017-05-21 18:10:28 +0000
395+++ doc/en/user-guide/writing_a_plugin.txt 2018-11-22 02:24:44 +0000
396@@ -40,8 +40,8 @@
397 Plugin searching rules
398 ----------------------
399
400-Bzr will scan ``~/.bazaar/plugins`` and ``breezy/plugins`` for plugins
401-by default. You can override this with ``BZR_PLUGIN_PATH``
402+Breezy will scan ``~/.config/breezy/plugins`` and ``breezy/plugins`` for
403+plugins by default. You can override this with ``BRZ_PLUGIN_PATH``
404 (see `User Reference
405 <../user-reference/configuration-help.html#brz-plugin-path>`_ for details).
406
407@@ -53,7 +53,7 @@
408 More information
409 ----------------
410
411-Please feel free to contribute your plugin to BzrTools, if you think it
412+Please feel free to contribute your plugin to Breezy, if you think it
413 would be useful to other people.
414
415 See the `Breezy Developer Guide`_ for details on Breezy's development

Subscribers

People subscribed via source and target branches