How to document branches on a Fossil project
(1) By Richard Hipp (drh) on 2018-12-10 21:22:16 [source]
Over on the SQLite project, we are finding that we would like to have commentary associated with a branch. We'd like to have a page with a multi-paragraph description for the purpose of a branch, for example. Perhaps even a place to put attachments.
One idea for how to do this is to have Fossil magically associate the branch named "xyzzy" with a Wiki page named "Branch: xyzzy". Whenever the branch appears on screen, there will be link to the wiki page, if such a page exists. And on the wiki page, there will be a link back to the timeline for the branch.
We could do something similar to associate a forum thread with a branch. If the title of the forum thread is "Branch: $NAME" then that forum thread is associated with the named branch, and there are hyperlinks going both ways.
Is this a reasonable way to provide comments and documentation associated with branches? Can anybody think of a better approach?
(2) By Stephan Beal (stephan) on 2018-12-10 21:30:46 in reply to 1 [link] [source]
Since the addition of embedded docs, i'm kinda partial to that approach, especially because it inherently branches with the rest of the content. For that particular approach the name "Branch:" wouldn't be appropriate because ":" is not a legal filename character on at least one common filesystems. If the goal is to have easy access to the branch docs from all branches of the tree, the wiki is probably the easier approach. Rather than looking for "Branch: name" in a forum/wiki title, my instinct would be to instead look for [branch-name], which would parse the brackets the same way timeline comments do. (Now that i think about it... do branch names parse that way in the timeline comments, or is that limited to version hashes?)
(3) By Richard Hipp (drh) on 2018-12-10 21:38:11 in reply to 2 [link] [source]
do branch names parse that way in the timeline comments, or is that limited to version hashes?
Currently that only works for checkin and ticket hashes, and wiki names. But it could be made to work for branches, I suppose.
(6) By Richard Hipp (drh) on 2018-12-10 22:26:39 in reply to 2 [link] [source]
Suppose wiki pages and forum threads are associated with a branch if their name exactly matches the name of the branch, without any "Branch:" prefix to confuse the filesystem.
For embedded documentation, perhaps there could be a setting that says "search for embedded documentation dealing with branches in this directory". So if the setting value was "branches" you could then create documents in the branches/ subdirectory with the names of branches, and Fossil would automatically associate the two.
(7) By Stephan Beal (stephan) on 2018-12-10 22:37:08 in reply to 6 [link] [source]
i like that far better than a magic name prefix. OTOH, maybe it should be a filename prefix which optionally includes a directory part, e.g. "docs/branch-", so that the docs could optionally be placed in the same directory as existing embedded docs?
(4) By Warren Young (wyetr) on 2018-12-10 21:55:55 in reply to 1 [link] [source]
We often have a wiki document for a large new feature's implementation plan. That document is often written long before the branch is created. It is usually modified at least once while the branch exists as our plans firm up. It may then survive after the branch is integrated with its parent to document the new feature.
The likely candidates here all have a lifetime independent of the branch.
How about using the tagging (?) feature of Fossil to associate a branch with either a wiki document or an embedded document instead? I may be misusing terms: I mean the feature that lets you say that this branch should have background color #aabbcc.
That way, you not only avoid the magical association between branch names and wiki page titles, the associated document can change over time as needed. Maybe the first link would be to a forum post started by an outsider, then to a wiki document as the feature idea firms up, then to an embedded document once the feature approaches release form. This attribute can show up in the "edit checkin" page, along with background color, the closed flag, etc.
The tag value could just be a relative URL fragment: /wiki?name=My+New+Feature. That'd let you point at anything on the same Fossil instance.
(5) By Richard Hipp (drh) on 2018-12-10 22:22:32 in reply to 4 [link] [source]
The main problem is that a branch is not an artifact. So there is no way to tag a branch, as there is nothing to attach the tag to.
We could tag a wiki page to say that it has an associated branch. But there does not seem to be a way to tag a branch to say that it has an associated wiki page.
(8) By Warren Young (wyetr) on 2018-12-10 23:38:16 in reply to 5 [link] [source]
A branch isn't an artifact, but a checkin is, and it can have propagating tags. The documentation reference tag for a branch is the nearest upstream docref tag, of which there may be several, if the documentation moves during that branch's lifetime.
(9) By anonymous on 2018-12-11 00:24:17 in reply to 8 [link] [source]
A branch may not be an artifact, but the first checkin of a branch is, so could tag that.
However, I prefer the semi-automatic association via page title prefix.
For the prefix, I think you could just do "Branch " and skip any potentially problematic punctuation. I expect occurrence of unintended associations will be low. Also, I don't see this as overly "magical".
(10) By Richard Hipp (drh) on 2018-12-31 02:19:50 in reply to 1 [link] [source]
The describe-objects-using-wiki branch implements a prototype of this idea. I have also added a few wiki pages to the Fossil self-hosting repository to illustrate the concept. In particular, the describe-objects-using-wiki branch itself has a wiki page that describes how the describe-objects-using-wiki branch works, which you can read for additional information.
The main server at https://fossil-scm.org/fossil is currently running off of the branch but (as of this writing) the back servers at www2 and www3 are still on trunk.
Please provide feedback.
(11) By sean (jungleboogie) on 2018-12-31 04:55:53 in reply to 10 [link] [source]
I like it! I think this kind of feature allows for the lengthy git commit messages we've seen before. IMO, that can be clumsy, but understandable why it's done that way in git - they don't have a wiki built in! https://github.com/postgres/postgres/commit/0a6ea4001a9dff64e9ba66f68855a59a1bf69bc9
Question, when viewing a commit when there's a known wiki page, like your example: https://www.fossil-scm.org/fossil/info/f17a5198f55845b6
Is it worth, perhaps in the context section, to call attention to the wiki page with a link to it? It might not be obvious to click on the tag link while at the timeline page.
(12) By Florian Balmer (florian.balmer) on 2018-12-31 17:18:41 in reply to 10 [link] [source]
A very handy feature!
I would like to make an addition to the above comment:
Might is be useful to draw attention to the extra wiki page for people reading just the timeline comments, i.e. without diving into the /info or /timeline?r=BRANCH detail pages?
There could be a symbol, say [+] or […], after the comment, or after the tag with an associated wiki page. Or, the whole comment could be a clickable link to the associated wiki page, but this may not work well with all Viewing Modes, and may not work either with multiple associated wiki pages (like, one for each tag, and another one for the check-in itself).
(13) By sean (jungleboogie) on 2018-12-31 17:22:52 in reply to 12 [link] [source]
Good input and that makes sense. You might not want to view check-ins just for the possibility for a wiki page.