Merge lp:~tzeentch-gm/trac-bzr/doc_updates into lp:trac-bzr

[Michael Gliwinski]

[Michael Gliwinski (tzeentch-gm)]

Few documentation updates regarding format of revision specifications, based on our recent conversation with Martin. Let me know if I should tweak anything further.

[Martin von Gagern (gagern)]

Nice. Thanks for saving me the work! A few comments, though:

1. The "two options" feel radically different to me: one affects the strings as I write them in Wiki text, and has to worry about keeping things unambiguous. The other affects the strings as Trac displays them to me, and although ambiguity there would degrade usability, it wouldn't break things completely. So I'd make this two distinct items, even if they are both related to possible future development.

2. Add a link to http://trac.edgewall.org/wiki/MultipleRepositorySupport alongside the one to https://blueprints.launchpad.net/trac-bzr/+spec/multirepo, as people might want to check the Trac development as well.

3. s/to do that/implementing it/ to avoid repetition and be more clear.

4. While you are at it, maybe you want to mention unsupported download links from bug #394204 as yet another known limitation. If you don't want to, I'll add that myself when I merge your changes.

review: Needs Fixing

[Michael Gliwinski (tzeentch-gm)]

> Nice. Thanks for saving me the work! A few comments, though:

No probs, thanks for the feedback.

> 1. The "two options" feel radically different to me: one affects the strings
> as I write them in Wiki text, and has to worry about keeping things
> unambiguous. The other affects the strings as Trac displays them to me, and
> although ambiguity there would degrade usability, it wouldn't break things
> completely. So I'd make this two distinct items, even if they are both related
> to possible future development.

Yes, I know what you mean, they both affect one user-visible feature but under the hood, they're in distinct places and unrelated.

> 2. Add a link to http://trac.edgewall.org/wiki/MultipleRepositorySupport
> alongside the one to https://blueprints.launchpad.net/trac-
> bzr/+spec/multirepo, as people might want to check the Trac development as
> well.
>
> 3. s/to do that/implementing it/ to avoid repetition and be more clear.
>
> 4. While you are at it, maybe you want to mention unsupported download links
> from bug #394204 as yet another known limitation. If you don't want to, I'll
> add that myself when I merge your changes.

I'll have a look to address those.

[lp:~tzeentch-gm/trac-bzr/doc_updates]

106. By Michael Gliwinski on 2010-01-27

Reorganized notes on addressing revspec limitations according to feedback.

107. By Michael Gliwinski on 2010-01-27

Added reference to MultipleRepositorySupport info page in Trac wiki.

108. By Michael Gliwinski on 2010-01-27

Fixed wording to make it clearer.

109. By Michael Gliwinski on 2010-01-27

Added info on unsupported download links.

[Michael Gliwinski (tzeentch-gm)]

I updated the branch, I see it's been picked up by LP but should I also set the review to resubmit or sth? (Sorry, don't see anything relevant in LP docs).

[Martin von Gagern (gagern)]

Looks fine now, thanks. Will commit this tomorrow. I'll first have to figure out the best way to integrate this into both trunk and the 0.3 branch.

review: Approve

[Michael Gliwinski (tzeentch-gm)]

Cool, thanks.
Maybe I should have done the changes against 0.3, then you'd be able to just merge it into trunk, no?

[Martin von Gagern (gagern)]

Yes, but never mind. Remember it if you should do future development, though.

You might however wish to change the Status of the branch from Development to Merged, as launchpad probably didn't catch that due to the fact that your head revision isn't integrated into trunk, as rebasing assigned new revision ids.

=== modified file 'HACKING'
--- HACKING	2009-12-17 18:38:17 +0000
+++ HACKING	2010-01-27 20:43:09 +0000
@@ -14,6 +14,11 @@
   a revision id by itself wouldn't give us an absolute path in that
   tree if there were multiple branches containing that revision.
 
+- Since Trac assumes revision numbers are global (as they are for svn)
+  and it doesn't give enough context for queries (e.g. path), there's no
+  way around this for now.  This may change in the future when multi-repo
+  support is available (Trac 0.12).
+
 - If there is only a single branch at the root of the directory
   configured as the bzr repository in Trac, then no branch name will
   be included in revision strings. In this case, simple revision
@@ -21,6 +26,19 @@
   trac-bzr will allow users to configure a "default branch" to obtain
   simple revision names even when dealing with multiple branches.
 
+- In order to be able to use simple revision numbers in TracLinks, one could
+  write a wiki syntax parser which translates e.g. specifications like
+  ``[tracsource:/foo/bar/baz@10]`` into link to the source browser with full
+  revision specification (i.e. ``.../browser/foo/bar/baz?rev=foo,10``) while
+  making sure things are unambiguous.
+
+- The way revision numbers are displayed in the source browser is controlled
+  by Trac's internal Genshi template.  In Trac >= 0.11 it would be possible
+  to affect that by writing a component which would act as postprocessing
+  hook with it's own Genshi template which reformats such links (i.e. the
+  hrefs would still need to use the same format but the visible text can be
+  rendered as simple numbers, e.g. check the ``Branches`` macro).
+
 - When generating revision strings, we prefer (dotted) revision
   numbers over bzr revision identifiers. Only when the revision in
   question hasn't been merged into that branch yet we emit a revision

=== modified file 'README'
--- README	2009-12-17 21:48:27 +0000
+++ README	2010-01-27 20:43:09 +0000
@@ -153,6 +153,10 @@
 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.
@@ -200,6 +204,41 @@
 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 colons (',').
+
+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 properly supports multiple
+repositories (possibly Trac 0.12, see Trac's `MultipleRepositorySupport`_
+page).  Also see `trac-bzr multirepo spec`_.
+
+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.
+
+.. _`MultipleRepositorySupport`: http://trac.edgewall.org/wiki/MultipleRepositorySupport
+.. _`trac-bzr multirepo spec`: https://blueprints.launchpad.net/trac-bzr/+spec/multirepo
+
+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 should be addressed in Trac itself.
+
+In fact an `upstream bug report`_ is already filled 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 encoding
 -------------
 Because at the moment Bazaar does not store information about encoding of text