Fossil Forum

Tighter integration of technotes
Login

Tighter integration of technotes

(1) By Torsten Berg (torstenberg) on 2020-12-09 22:12:41 [link] [source]

I love the technotes in fossil. E.g., I use them for the minutes of my meetings when deciding on new features. Thus, all decisions which have an influence on the code are documented on the right spot in the timeline. This is neat and convenient.

The documentation states that technotes are a special kind of wiki page. Logically, technotes can be created from within the wiki.

However, technotes are not shown in the wiki. They are not part of the list of pages in the wiki. They are only shown in the timeline. Depending on the settings, you even have to switch the timeline view in order to see them since technote may not be visible by default. (This is different from the fossil wiki ls command which is able to show technotes).

The documentation also states that technotes do not have a page name. This may be a reason not to show them in the wiki (and being an event originally, plus representing a point in time, it is somewhat logical to show them in the timeline despite being wiki pages).

However, technotes have a "timeline comment" which in practical terms is the same as a title or "page name". So, they could in principle be shown by "title", just as the normal wiki pages.

Therefore, I find the integration of technotes in fossil can be a bit more consistent. Can we have the following:

  • A link on the "Wiki Links" (/wiki) page: "List of All Technotes available on this server" which links to the timeline view of all technotes.

  • When viewing a technote, also show the "timeline comment" as a kind of title together with the technote content (either above the menu bar together with with the technote artifact ID, or (preferred) below the menu bar

  • An attachment can only be added to a technote after it has been created (you need to go to the timeline, choose the technote, choose attach, then actually attach the file. Why not enable attaching files at creation time?

  • When viewing a technote (coming there from the timeline), there is a menu with 'Attach', 'Context', 'Detail' and 'Edit'. Clicking on 'Detail' you get some more data, like the "timeline comment". This view could also be the default view and would consequently have a "title" already. Especially, since you cannot go back to the previous view. Now the menu shows 'Attach', 'Context', 'Edit' and 'Plain' -- but 'Plain' is not the opposite of 'Detail', it is something completely different -- and the order of the menu items is changed ('Edit' being rightmost or not, depending on the view). The viewing mode 'Plain' could more clearly be called 'Source' since that is how it appears to be.

Thanks, Torsten

(2) By Richard Hipp (drh) on 2020-12-09 23:19:03 in reply to 1 [link] [source]

Technotes derived from the idea of an "Event" in CVSTrac. I used events in CVSTrac a lot, to do things like provide release notes for official releases. So naturally, when I was designing Fossil (based on my experience with CVSTrac) I included technotes in the design.

But, for me at least, technotes have not been as useful in Fossil as they were in CVSTrac. I'm not sure why this is. Perhaps it has to do with the ease of branching in Fossil. With CVS, pretty much everything was on trunk. Branching was difficult and clunky and generally avoided. So everything ended up being very linear. As a result, a technote would fit right into the "flow". But technotes in Fossil do not belong to a branch - they are just a point in time. So they do not seem to fit into the flow as well as they did with CVSTrace. They somehow they seem less useful. And as witness to this I have scarcely used them.

I'm glad somebody finds technotes useful though! I'm happy to consider patches to make them better. The list of ideas above seem to be a good start.

(3) By MBL (RoboManni) on 2020-12-10 08:23:31 in reply to 2 [link] [source]

In TechNotes and Commit messages it is possible to have links to refer to related Forum treads or items (as hyperlink URL, interlink or what else?).

In Forum posts it is possible to have links to timeline commits (I am not sure if linking to TechNotes also is possible but I guess it is the same).

What is missing is the hyperlinking possibility from timeline to Forum posts or a whole Forum thread for non-committing people by mentions in such forum posts.

On the other side each Commitment as well as TechNote has a time stamp and a hash code. In case a Forum post refers to such a specific hash code it would be of great benefit to become enabled to see these mentions as a short list of possible links in the timeline to jump to these Forum posts. (Forum capability is required for this to work, otherwise the listed mentions cannot be links.)

These links would not be added to the timeline by the capability of a developer with right for commitments but by the capability of a registered forum user (forum reader).

Searching through the timeline could this way help finding discussions in the forum. What a great enhancement could this be!

By only considering mentions in forum posts from registered users (not from anonymous), this would encourage to register also.

One has always be first. Forum posts can refer to existing time line items, TechNotes and Commitments could refer to existing Forum entries. But new posts in forum would need amendments to existing messages to get included at a later point of time. My proposal could solve this situation and separate the capabilities required to do it.

(4.1) Originally by Torsten Berg (torstenberg) with edits by Stephan Beal (stephan) on 2021-03-15 07:34:59 from 4.0 in reply to 2 [link] [source]

Thanks for considering such changes!

I just noticed another phenomenon. As technotes can be given a tag, these tags will be listed under /taglist on the server as non-propagating tags.

The linke from that page, however, links to Check-ins. It seems I cannot construct a link to the timeline view which is able to show only technotes having a specific tag name:

http://localhost:8080/timeline?n=50&y=e&t=myTagName&ms=exact

This only results in the output

0 check-ins tagged with "myTagName"

I would have expected

0 technotes tagged with "myTagName"

if there were any, but there are technotes tagged with that tag.

I hope I can find the time to provide some patches for my ideas (in my OP) and also for this phenomenon which seems like a bug.

(Edited by Stephan to remove hard-coded code element style, as it is illegible in some skins (white on white).)

(5) By Stephan Beal (stephan) on 2020-12-10 15:32:25 in reply to 4.0 [link] [source]

I just noticed another phenomenon. As technotes can be given a tag, these tags will be listed...

I would have expected...

The data model actually allows tagging any and all artifacts, noting that tags themselves are artifacts, so it's technically possible to tag a tag of a tag of a tag. However, the various UIs for showing/dealing with non-checkin tags have never really been developed.

The CLI tag command only allows tagging checkins, but there seems to be little reason it cannot be extended to tag arbitrary artifact types. (Since you're already patching related code...)

(9.1) By Dan Shearer (danshearer) on 2021-03-15 11:49:47 edited from 9.0 in reply to 5 [link] [source]

Good stuff Torsten.

Although there isn't any way yet to assign or use a value for a non-commit tag, we can create from the commandline.

As a confused newcomer to tags, I summarised the answer to What is a technote?.

Here is a command to create multiple non-commit tags from that that thread:

fossil wiki create TestTechnote -t now --technote-bgcolor lightgreen --technote-tags "wuppernoodle blangerquokkums sookfipardi"

which creates these T cards in the artifact:

T +bgcolor * lightgreen

T +sym-blangerquokkums *

T +sym-sookfipardi *

T +sym-wuppernoodle *

The three --technote-tags show up in the Fossil list of alltags, and they don't have any value assigned.

Dan Shearer

(10) By Stephan Beal (stephan) on 2021-03-15 12:06:20 in reply to 9.1 [link] [source]

which creates these T cards in the artifact:

That seems peculiar, though: sym- tags have historically been limited to checkins. The docs say:

All tags that begin with "sym-" are symbolic name tags. When a symbolic name tag is attached to a check-in, that allows you to refer to that check-in by its symbolic name rather than by its hexadecimal hash name. When a symbolic name tag propagates (as does the sym-trunk tag) then referring to that name is the same as referring to the most recent check-in with that name. Thus the two tags on check-in 1 cause all descendants to be in the "trunk" branch and to have the symbolic name "trunk."

Maybe it's an omission, but they make no mention of symbolic tags in the context of any other artifact type.

It would interest me to know whether looking up your technote by the name "sookfipardi" works or not. e.g. using:

fossil whatis sookfipardi

Why the --technote-tags flag would prefix the tags with sym- is a mystery to me but that seems like two bugs: one for applying a sym- prefix to the tag and another for allowing multiple symbolic names to be applied at once (even if symbolic names are legal for a technote, adding multiples to the same technote seems like a path to madness).

That said: i'm not 100% certain that they won't work as expected. Maybe they do, in which case feel free to chide me for my ignorance on the topic.

(6) By Torsten Berg (torstenberg) on 2020-12-11 14:37:19 in reply to 2 [link] [source]

OK, so the code for the first item is trivial. Just add these two lines (or some other similar wording) to wiki.c after line 365:

@ <li> %z(href("%R/timeline?y=e"))List of All Tech-notes</a>
@      available on this server (shown in the timeline).</li>

(7) By Torsten Berg (torstenberg) on 2021-03-15 07:14:46 in reply to 6 [link] [source]

How about taking this into version 2.15?

(8) By Stephan Beal (stephan) on 2021-03-15 07:35:44 in reply to 7 [link] [source]

How about taking this into version 2.15?

Done: fossil:c00e5d60a0868055

(11) By Dan Shearer (danshearer) on 2021-03-15 13:53:00 in reply to 1 [source]

Torsten Berg (torstenberg) wrote on 2020-12-09 22:12:41:

technotes do not have a page name... technotes have a "timeline comment"

Yes, and it isn't obvious to someone new to technotes. Unless someone objects, I will change the help text for "fossil wiki create" to mention the technote name like this:

fossil wiki (create|commit) (PAGENAME | TECHNOTE-NAME) ?FILE? ?OPTIONS? 

The unique handle for a technote is its time, the time it appears in the timeline not its creation time. This too can be confusing at first. I propose to change the text of "fossil wiki create" to say:

         -t|--technote DATETIME      Specifies the timestamp of
                                     the technote to be created or
                                     updated. The timestamp specifies when
                                     this technote appears in the timeline
                                     and is its permanent, unique handle.
                                     When updating a technote the most
                                     recently modified tech note
                                     with the specified timestamp will be
                                     updated.

The above correctly describes how technotes work and I think they will be useful to me.

One thing I am still confused about is TECHNOTE-ID. You can specify a TECHNOTE-ID when updating a technote from the commandline, but not when creating. Is TECHNOTE-ID an obsolete concept? Since I can't create a technote-id from the commandline, then it is unsurprising I can't get one to display using

fossil -t -s
.

Can anyone tell me what TECHNOTE-ID is?

Dan Shearer

(12) By David Vines (djvines) on 2021-03-15 18:43:34 in reply to 11 [link] [source]

I think I'm one of the few people to use technotes - and to be fair that's only for my own personal projects.

I believe that the technote-id is the hash-id of the technote and is used to disambiguate when two technotes are created with the same timestamp and then you want to update one of the technotes via the CLI - there's a couple of tests in wiki.test to validate that this can be done.

Of course in practise you're unlikely to have actually need two technotes with exactly the same timestamp, but the technote-id is to allow that corner case to be resolved without preventing the creation of the second technote.

(13) By Dan Shearer (danshearer) on 2021-03-16 15:21:43 in reply to 12 [link] [source]

David Vines (djvines) wrote on 2021-03-15 18:43:34:

I believe that the technote-id is the hash-id of the technote...

Yes that appears to be correct, in wiki.c:

     if( showIds ){
        const char *zUuid = db_column_text(&q, 1);
        fossil_print("%s ",zUuid);
      }

And I have test cases where

fossil wiki ls -s -t
work every time, listing the uuid. Now I am trying to re-create the test case where it does not.

Thanks,

Dan Shearer