Fossil Forum

Tech-Note, is there a doc, CLI guidance or discoverable web UI?
Login

Tech-Note, is there a doc, CLI guidance or discoverable web UI?

(1) By Larry Brasfield (larrybr) on 2021-02-17 02:45:25 [link] [source]

I have heard of the "tech-note" by reading this forum. Suddenly, I have some use for it. However, fossil help --everything shows it to be pretty much a WUI feature (web UI) [a], with no exposure at the CLI interface (that I can discern.)

[a. I assume that when, for /whatever commands, there are words about GET and POST traffic, but nothing about command line parameters, it is WUI-only. ]

A search of this forum shows some discussion of the feature, and there are tantalizing hints from "help --everything" that it is implemented. My rummaging around in the WUI has turned up nothing yet. (I've clicked on a great many parts of the timeline that look clickable, but I'm not sure what all is clickable.)

Is it a real feature? Is there some guidance re activating or using it? In the site or application help rather than in the code or forum dredging?

Wasn't the feature malfunctioning just recently? For that to happen, there must have been some usage, right?

I'm feeling kind of stupid about this, so there is no need to inform me of that.

(2) By sean (jungleboogie) on 2021-02-17 02:56:02 in reply to 1 [link] [source]

Hi Larry,

Are you asking if technote is real? Yes, it is.

Help page: https://fossil-scm.org/home/help?cmd=/technote

It used to be called event.

Tech note example.

Tech notes are viewable in the timeline.

AFAIK, it's not accessible via cli. While there are many things you can do in the cli, you can't do everything, and that's on purpose. I think it would be painful to feed in a tech note in MD or fossil wiki format, hoping you get all formatting and layout correct.

(3) By Stephan Beal (stephan) on 2021-02-17 02:58:17 in reply to 2 [link] [source]

AFAIK, it's not accessible via cli.

Technotes are essentially a special case of wiki pages and can be manipulated via the wiki command.

(4) By sean (jungleboogie) on 2021-02-17 03:02:50 in reply to 3 [link] [source]

Good info!

This is another good case where cross-linking in the help pages could be helpful.

https://fossil-scm.org/home/help?cmd=/technote could link to https://fossil-scm.org/fossil/help/wiki

(6) By Stephan Beal (stephan) on 2021-02-17 03:08:44 in reply to 4 [link] [source]

https://fossil-scm.org/home/help?cmd=/technote could link to https://fossil-scm.org/fossil/help/wiki

To do that we'd have to alias the /wiki and /technote pages/commands to be equivalent. The help index is created directly from the command/page dispatcher's contents, and has no facility for listing anything which isn't itself a command or page.

(7) By sean (jungleboogie) on 2021-02-17 03:12:51 in reply to 6 [link] [source]

Sorry, I meant the "See also" section, such as in pull.

(9) By Stephan Beal (stephan) on 2021-02-17 03:18:16 in reply to 7 [link] [source]

Sorry, I meant the "See also" section, such as in pull.

LOL! i didn't even know it could do that.

(8) By Larry Brasfield (larrybr) on 2021-02-17 03:16:31 in reply to 3 [link] [source]

Thanks to Stephen and Sean both. It looks like I can proceed with those tips.

I think that "tech-note" needs an appearance in the permutated index and the keyword index. Maybe "technote" too. I suspect that my search was thrown off by getting the notion that "tech-note" was the feature's name. Even help --everything is helpful on this feature with a search for "technote". Silly me.

I can see how to view technotes from the UI, and now how to create one from the CLI using the 'wiki' subcommand. But creating one from the WUI has escaped my now somewhat better informed search. I may be back when that search has been thoroughly performed.

BTW, it is the tediousness of searching in a GUI or the WUI for deeply nested features that make 'help help --everything' a treasure. During my earlier search, I neglected to pull down every combo box. (I'm not used to such being used to navigate rather than selecting values. Now I know.)

Even if this seems a bit plaintive, I am appreciative too. Thanks again.

(10) By Dan Shearer (danshearer) on 2021-02-26 14:57:46 in reply to 3 [link] [source]

Stephan Beal (stephan) wrote on 2021-02-17 02:58:17:

Technotes are essentially a special case of wiki pages and can be manipulated via the wiki command.

I tried this:

fossil wiki create TestTechnote -M markdown --technote-bgcolor red

Which correctly creates an artifact recorded as a technote according to fossil timeline. However it isn't visible in the web timeline UI. I have selected "all" types to view, and used /timeline?y=e.

I tried adding -t TechnoteTagHere to the create command with no change.

What am I missing?

Dan Shearer

(11) By Dan Shearer (danshearer) on 2021-02-26 17:10:46 in reply to 10 [link] [source]

The previous example omitted the -t parameter. But I did use it in my tests :-)

I have never created a wiki page before, and I made various mistakes. Things I needed to get right before technotes appeared on the timeline:

  • A remote repo and a local repo can have different web ui timeline defaults: my local fossil ui defaulted to "checkins" and the remote to "all types". I have no idea how this happened but it confused me for a little
  • you need to use fossil sync to force the local repo to send technotes to the remote. You don't need to do this for tickets, and I assumed wiki pages would be like tickets
  • one use of the -t switch is -t TECHNOTE-ID . I think TECHNOTE-ID is exclusively about editing an existing technote, and is an ordinary Fossil artefact id. It's not some other technote namespace one can curate.
  • the main use of the -f switch is -t DATETIME, which is where to put the technote into the timeline. I have only successfully so far used a DATETIME of 'now'. I don't know where "now" fits in to Fossil time specifications

The following creates a technote:

fossil wiki create SomeTechnoteName -t now -M markdown --technote-bgcolor blue

This will prompt for input in the same way as fossil commit comments. Equally you can specify a filename at the end of the command.

Dan Shearer

(13) By Stephan Beal (stephan) on 2021-02-26 17:22:24 in reply to 11 [link] [source]

You don't need to do this for tickets, and I assumed wiki pages would be like tickets

Sure you do. No part of the web interface automatically syncs with the remote. However, all "normally syncable" content - checkins, wiki, tickets, forum, etc. - are transferred via a single sync/pull/push.

I think TECHNOTE-ID is exclusively about editing an existing technote, and is an ordinary Fossil artefact id. It's not some other technote namespace one can curate.

That seems to be the case:

$ f wiki create X -t MyTechnote -M markdown --technote-bgcolor red
testing again
Created new tech note 2021-02-26 17:15:02.

i've never used the technote CLI interface, so can't comment on its quirks, but that certainly seems like a confusing one.

This will prompt for input in the same way as fossil commit comments. Equally you can specify a filename at the end of the command.

Or pipe from stdin. Or type it all on stdin and tap the EOF sequence when you're done (ctrl-D on most Unices).

(12.1) By Stephan Beal (stephan) on 2021-02-26 17:14:38 edited from 12.0 in reply to 10 [link] [source]

fossil wiki create TestTechnote -M markdown --technote-bgcolor red

What am I missing?

i think that actually created a wiki page. To get a technote (if i'm reading the help right, noting (haha) that the technote feature was added by someone else):

fossil create -t DATETIME -M markdown --technote-bgcolor red

technotes are only named by a random ID or datetime, not a wiki-like name.

Trying your input:

$ f wiki create MyNote -M markdown --technote-bgcolor red
test test test
^D
Created new wiki page MyNote.

$ f wiki ls
MyNote

But this works:

$ f wiki create MyTechnote -t 2021-02-26T18:12 -M markdown --technote-bgcolor red
test test test
^D
Created new tech note 2021-02-26 18:12:00

$ f wiki ls
MyNote
$ f wiki ls -t
2021-02-26 18:12:00

The name given to create actually doesn't do anything for technotes (that they're silently accepted is arguably a bug):

$ f wiki export -t '2021-02-26 18:12:00'
test test test
$ f wiki export -t MyTechnote
technote [MyTechnote] not found

(14.2) By Dan Shearer (danshearer) on 2021-02-26 20:43:37 edited from 14.1 in reply to 12.1 [source]

What is a Technote?

I know what a technote is now, although I don't know how to use them. And together we've figured out how to create technotes on the commandline.

Fossil did use a technote once, back for the Fossil 2.7 release notes so they must be good. I have wondered if technotes might be a developer-facing indication of a change in tree or team status, a bit like the way a formal release with a number is an outward-facing statement of status.

How wiki create -t actually works

Stephan Beal (stephan) wrote on 2021-02-26 17:14:38:

The name given to create actually doesn't do anything for technotes (that they're silently accepted is arguably a bug)

Nope, that name does get preserved and is displayed in the timeline, both web and commandline. You were using the wiki ls command instead of timeline. We were also suffering from a confusing misunderdocumentation as follows but I don't see any bugs.

So let's refer to the technote object definition. Valid card types for a technote object include:

C Comment

The C card contains text that is displayed on the timeline for the technote.
The C card is optional, but there can only be one. 

This is PAGENAME described in fossil help wiki. The pagename becomes the C card, and fossil timeline displays it. It is not silently discarded. The commandline help text should probably add "| TECHNOTE NAME" or similar.

D time-and-date-stamp

the date and time when the technote artifact was created. 
This is different from the time at which the technote appears on the timeline. 

So the D card is automatic as we expect from Fossil, and not specified on the commandline. The commandline help text should probably say "the time of creating a technote is not relevant to where it appears in the timeline, except in the special case of 'now'".

E technote-time technote-id

When there are multiple artifacts with the same technote-id, the one with the
most recent D card is the only one used

technote-time: this is when the technote is to appear in the timeline. If we specify -t technote DATETIME then the technote appears at DATETIME. The special case is -t technote now, when the D card and the E technote-time card will be identical. I wonder if 'now' is an alias unique in Fossil.

technote-id: this is an automatically-generated Fossil hash, unique to this technote but not this artifact. All revisions of this technote will have this hash. I presume it is only used when it is time to either display/append to the latest technote version, or verifying the integrity of the database because the P card is only ever supposed to point to another technote with the same technote-id.

The parameter --technote-tags TAGS is interesting. Because the object format has a T card like this:

T +tag-name * ?value?

The format of the T card is the same as described in Control Artifacts section
above, except that the second argument is the single character "*" instead of 
an artifact ID and the name is always prefaced by "+". The * in place of the
artifact ID indicates that the tag or property applies to the current artifact.
It is not possible to encode the current artifact ID as part of an artifact,
since the act of inserting the artifact ID would change the artifact ID, hence
a * is used to represent "self". The "+" on the name means that tags can only
be add and they can only be non-propagating tags. In a technote, T cards are
normally used to set the background display color for timelines.

Which means that this command:

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

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. But I have no idea what else can be done with them, if anything. I don't think they correspond in any way to tags in the sense of "branch", but I might be wrong.

Dan Shearer

(15) By Stephan Beal (stephan) on 2021-02-27 01:24:17 in reply to 14.2 [link] [source]

The three --technote-tags show up in the Fossil list of alltags, and they don't have any value assigned. But I have no idea what else can be done with them, if anything. I don't think they correspond in any way to tags in the sense of "branch", but I might be wrong.

Briefly on my way out the door again...

See the "Tags and Properties" section of https://fossil-scm.org/home/doc/trunk/www/branching.wiki for the distinction between branches and non-branch tags. Tags normally don't have values in fossil but they are allowed to (and a few of the special case tags, like color, need a value). In the case of that command there's no way to set a value unless (perhaps - haven't checked the code) the command is looking for x=y and splitting on that '='. Any such value would be purely FYI - fossil couldn't do anything with it. (To be honest, i'm pleasantly surprised that it treated the 3 words as separate tags.)

Having a custom tag on a non-checkin isn't currently all that useful. Only checkins can generally make use of them (fossil update release-x.y), but improving upon that is one of the points in the GSoC list.

(5) By Stephan Beal (stephan) on 2021-02-17 03:06:16 in reply to 1 [link] [source]

, with no exposure at the CLI interface (that I can discern.)

See the wiki command. It's primarily a UI feature, though.

Wasn't the feature malfunctioning just recently? For that to happen, there must have been some usage, right?

It wasn't actually being used at the time - a test run of libfossil's artifact parser uncovered the misbehavior.

That said, i use it as kind of a "dev diary" or "announcement" feature from time to time:

https://fossil.wanderinghorse.net/r/libfossil/timeline?y=e

Is there some guidance re activating or using it?

The wikihelp page can (with the correct access rights) be used to create technotes.

Ideally, the new wiki editor could be used to edit technotes, but i simply didn't consider that use for it when implementing it at the time, and now it's a low-priority TODO.