~jteh/trac-bzr/newDeps

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
===================================
Multi-branch Bazaar plugin for Trac
===================================

.. contents::

This plugin is based on earlier plugins.  Its main innovation is to make
multiple branches available, the way Trac normally does.

| Copyright (C) 2005 Edgewall Software
| Copyright (C) 2005-2006 Christian Boos <cboos@neuf.fr>
| Copyright (C) 2005 Johan Rydberg <jrydberg@gnu.org>
| Copyright (C) 2006 Yann Hodique <hodique@lifl.fr>
| Copyright (C) 2006 Jelmer Vernooij <jelmer@samba.org>
| Copyright (C) 2006 Lukas Lalinsky <lalinsky@gmail.com>
| Copyright (C) 2006 Marien Zwart <marienz@gentoo.org>
| Copyright (C) 2006,2007 Panoramic Feedback <abentley@panoramicfeedback.com>
| Copyright (C) 2006,2008,2009,2010 Jelmer Vernooij <jelmer@samba.org>
| Copyright (C) 2009,2010,2011 Martin von Gagern <Martin.vGagern@gmx.net>
| Copyright (C) 2009 Hendrik van Antwerpen
| All rights reserved.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA


Features
========

Repository views
----------------
Supports all major Trac views and "changeset:" notation.

Allows a collection of branches to be treated as a "trac repository",
regardless of whether they are related or in the same bzr repository.

Follows symlinks to branches.

Wiki Macros
-----------

Branches
........
The plugin provides a macro called ``[[Branches]]``
to list all available branches, together with some information about them,
like the current revision number and the time of the last commit.


Installation
============
Basically the `Plugins section of the Trac Guide`__ applies to the
installation of trac-bzr as well.
It gives you several options how to install a plugin.

.. __: http://trac.edgewall.org/wiki/TracPlugins

The bundled bzr plugin can be installed either by using setup.py
to install or by copying the ``bzrplugin`` directory into
``~/.bazaar/plugins`` and renaming to ``trac``.

System-wide using easy_install
------------------------------
Executing the command "``easy_install TracBzr``" as root should install
the plugin system-wide, making it available to all trac environments
on that system.

Per-environment using plugin egg file
-------------------------------------
You can download the egg file corresponding to your python version and
place it in the ``plugins`` directory of a Trac environment.

Building from source
--------------------
If you want to build trac-bzr from source, you can either grab a
source release tarball or a checkout of a development branch. Many
development branches are `listed on launchpad`__. Once you have
obtained such a source tree, execute "``python setup.py install``" to
install the plugin system-wide, or "``python setup.py bdist_egg``" to
obtain an egg file for installation in a single Trac environment.

.. __: https://code.launchpad.net/trac-bzr

Requirements
------------
In order to function properly, trac-bzr requires the packages listed below.

These dependencies are not handled by setuptools, because otherwise
the plugin would fail to load if one of the dependencies wasn't
installed with setuptools or similar.

Python 2.4
  This plugin uses bzrlib directly, so it requires Python 2.4 or greater.

Trac 0.10
  Some features may only work with Trac 0.11 or even Trac 0.12.

Bazaar 2.0
  This plugin should work with Bazaar 2.0.
  Earlier versions may or may not work.

Configuration
=============
To configure trac-bzr, you'll have to edit the ``trac.ini`` file of
your Trac environment.

Required configuration
----------------------
After installing, you'll want to set the following values::

  [components]
  tracbzr.* = enabled

  [trac]
  repository_type = bzr
  repository_dir = /path/to/collection/of/bzr/branches

components
..........
This should include "``tracbzr.* = enabled``" to enable all features
provided by the plugin.
As an alternative, you can enable or disable specific components
providing specific features, e.g. in order to disable the wiki macro
provider.
Use the Trac web admin plugin interface (Trac 0.11 or later) or have a
look at the sources to find out which components are available.

repository_dir
..............
This should point at the directory containing your branches.  This directory
does not have to be a repository.  trac-bzr doesn't require branches to
be related, though that is permitted, of course.

repository_type
...............
This should be "bzr".

Optional configuration
----------------------
There are some optional settings you can configure for trac-bzr.
If you do not specify them, the following defaults will be used instead::

  [tracbzr]
  primary_branches = trunk
  include_sideline_changes = True

primary_branches
................
This is a comma-separated ordered list of the main branches of your project.
You may also specify `glob patterns`_ in this list to match multiple branches.

Note that the pattern must match from the root of repository_dir, so if you
set it to e.g. a directory containing sub-directories which in turn contain
branches, you should set primary_branches to ``*/BRANCH``.

The Branches_ wiki macro will list branches in the order specified by this list.
The timeline view will try to associate changesets with branches in the
specified order.
In both cases, branches not matched by any list item will be inserted at the
end of the list, as if you had ended the list with ``,*``.
Branches matched by a single list item will be sorted alphabetically.

.. _`glob patterns`: http://docs.python.org/library/fnmatch.html

include_sideline_changes
........................
This boolean flag selects whether or not sideline changes, i.e. those
denoted with dotted revision numbers, are included in the list of all
changes. This affects the output of the ``get_changesets`` method,
which in turn influences the events listed in the timeline view.

Note that there might be other plugins using that information as well,
so there might be other components beside the timeline view that get
affected by this setting.

Performance
===========

Some user-level operations are rather slow, because Trac's assumptions
about which repository operations are cheap vs expensive doesn't match
Bazaar's design.

Revision numbers
----------------

One of the problems is the mapping between revision identifiers and
revision numbers. The `Bazaar Revision Numbering Cache Plugin`__ might
help for this problem, although it's experimental and hasn't been
tested with trac-bzr extensively enough. Feedback welcome.

.. __: https://launchpad.net/bzr-revnocache

Last modifications
------------------

Another problem is that bzr has a different idea about the last
modification of a directory. In svn, any modifications of directory
contents is said to modify the dir as well. In bzr, only changes to
the set of files in a directory are counted.

Investigations are in progress about how to solve this problem,
probably through the use of caches.

Known Problems and Limitations
==============================

Bogus changesets
----------------
This plugin introduces the bogus changeset "current:", which is used as
the last-revision for directories that are not branches.  It also provides
"null:", which is part of Bazaar's theoretical model, but usually hidden.

Hidden nested branches
----------------------
Because Trac, like Subversion, doesn't differentiate between "source file
namespace" and "branch namespace", it is impossible to view branches whose
directories are directly inside other branches' directories.

Revision order
--------------
If two changesets are not related to one another by some direct ancestry,
i.e. if neither one is an ancestor of the other, then revisions are sorted by
timestamp instead.
In case of a clock skew this can lead to inconcistent results,
as transitivity isn't guaranteed for this approach.

Bracket syntax
--------------
Trac does not to recognize bzr revision strings in its bracket notation,
e.g. ``[tree,25]``.
However, you can use the changeset notation instead, e.g.
``changeset:tree,25``.

Revision specification format
-----------------------------
Since Trac repository queries don't give trac-bzr enough context, revisions
have to be specified and are presented in the format ``PATH_TO_BRANCH,REV``
where ``PATH_TO_BRANCH`` is the path to branch (or object within the branch
like directory or file) relative to repository_dir, with slashes ('/')
replaced with commas (',').

This is visible when browsing the branches via Trac's source browser and this
is also what you have to use in TracLinks.

This may be improved in the future when trac-bzr adds_ proper support
for the multiple repository interfaces added_ in Trac 0.12.

In the meantime, if you have an urgent need to address that and are able
to spend some time implementing it, have a look at HACKING document for
possible approaches in Trac 0.11 and below.

.. _adds: https://blueprints.launchpad.net/trac-bzr/+spec/multirepo
.. _added: http://trac.edgewall.org/wiki/MultipleRepositorySupport

Unsupported download links
--------------------------
Using download links in source browser (under "Download in other formats"
heading) is not supported.  For details see `bug 394204`_, in short this is
a problem which should be addressed in Trac itself.

In fact an `upstream bug report`_ is already filed in and a patch is
available, so if you're interested in this feature check it out and discuss
any issues with it upstream.

.. _`bug 394204`: https://bugs.launchpad.net/trac-bzr/+bug/394204
.. _`upstream bug report`: http://trac.edgewall.org/ticket/8919

File content encoding
---------------------
Because at the moment Bazaar does not store information about encoding of text 
files, you may want to change the default character set used by trac. 
By default trac use encoding iso-8895-15 to show content of your files. 
If you need to change this option, you need to edit trac.ini of your project. 
In section "trac" you need to change parameter named "default_charset". E.g. 
for russian files::

  [trac]
  default_charset = cp1251

File name encoding
------------------
In order to process file names with non-ascii characters, the python
interpreter must be able to represent these names as paths in the
local file system. This is still required_ even if the non-ascii name
occurs only within a treeless branch under some ascii branch name, so
that the file itself isn't actually present in the file
system. Different steps might be required to configure the file system
encoding depending on your operating system and the method you use to
start trac.

You can see the configured file system encoding when you look at the
"System Information" section of the "About Trac" page as a user
equipped with the `CONFIG_VIEW`_ permission. There you will find an
entry labeled "FSEncoding" which will tell you what encoding python
believes_ your file system is using.

For Trac started as a CGI_ from Apache HTTPD under Linux, you'd use
the SetEnv_ directive to change the LANG_ environment variable. The
same approach might work for other combinations as well.

::

  LoadModule env_module modules/mod_env.so
  SetEnv LANG en_US.utf8

Setting the 'LANG' entry of `os.environ`_ inside the python code used
to start Trac might work as well, but it might fail in cases where the
file system encoding is determined and cached before that setting is
made.

.. _required: https://bugs.launchpad.net/trac-bzr/+bug/675014/comments/3
.. _`CONFIG_VIEW`: http://trac.edgewall.org/wiki/TracPermissions
.. _believes: http://docs.python.org/library/sys.html#sys.getfilesystemencoding
.. _CGI: http://trac.edgewall.org/wiki/TracCgi
.. _SetEnv: http://httpd.apache.org/docs/2.2/mod/mod_env.html#setenv
.. _LANG: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_02
.. _`os.environ`: http://docs.python.org/library/os.html#os.environ

Bazaar plugin
=============
There is a Bazaar plugin bundled with this project which can
automatically notify trac of new commits. To enable this, set the
``trac_project`` option in the Bazaar config to the path of your trac
environment.

For example, if your trac environment lives in
``/home/trac/myproject``, run::

  $ bzr config trac_project=/home/trac/myproject

in your Bazaar branch.

This plugin also adds a new bzr subcommand ``bzr close-trac-bugs``
which can automatically mark trac bugs as closed based on the Bazaar
commit properties created with ``bzr commit --fixes``.

.. cut long_description here

.. vim: ft=rst

.. emacs
   Local Variables:
   mode: rst
   End: