What Is A "Technote"?
In Fossil, a "technical note" or "technote" (formerly called an "event") is a special kind of wiki page that is associated with a point in time rather than having a page name. Each technote causes a single entry to appear on the Timeline Page. Clicking on the timeline link will display the text of the technote. The wiki content, the timeline entry text, the time of the technote, and the timeline background color can all be edited.
As with check-ins, wiki, and tickets, all technotes automatically synchronize to other repositories. Hence, technotes can be viewed, created, and edited off-line. And the complete edit history for technotes is maintained for auditing purposes.
Possible uses for technotes include:
- Milestones. Project milestones, such as releases or beta-test cycles, can be recorded as technotes. The timeline entry for the technote can be something simple like "Version 1.2.3" perhaps with a bright color background to draw attention to the entry and the wiki content can contain release notes, for example.
- Blog Entries. Blog entries from developers describing the current state of a project, or rationale for various design decisions, or roadmaps for future development, can be entered as technotes.
- Process Checkpoints. For projects that have a formal process, technotes can be used to record the completion or the initiation of various process steps. For example, a technote can be used to record the successful completion of a long-running test, perhaps with performance results and details of where the test was run and who ran it recorded in the wiki content. The technote can be added from a script.
- News Articles. Significant occurrences in the life cycle of a project can be recorded as news articles using technotes. Perhaps the domain name of the canonical website for a project changes, or new server hardware is obtained. Such happenings are appropriate for reporting as news.
- Announcements. Changes to the composition of the development team or acquisition of new project sponsors can be communicated as announcements which can be implemented as technotes.
- Signed Checksums. Technotes containing cryptographically signed checksums can be linked to repository artifacts, thereby creating a traceable, auditable chain so that users can readily verify the integrity and authenticity of project deliverables. And the command line interface to technotes enables embedding such processes in scripts.
No project is required to use technotes. But technotes can help many projects stay better organized and provide a better historical record of the development progress.
Viewing Technotes
Because technotes are considered a special kind of wiki, users must have permission to read wiki in order read technotes. Enable the "j" permission under the /Setup/Users menu in order to give specific users or user classes the ability to view wiki and technotes.
Technotes show up on the timeline. Click on the hyperlink beside the technote title to see the complete text.
Creating, Editing and Viewing Technotes
There is a hyperlink under the /wikihelp menu that can be used to create new technotes. And there is a submenu hyperlink on technote displays for editing existing technotes.
Technotes can also be created using the wiki create command:
fossil wiki create TestTechnote -t now --technote-bgcolor lightgreen technote.md
Created new tech note 2021-03-15 13:05:56
This command inserts a light green technote in the timeline at 2021-03-15 13:05:56, with the contents of file technote.md and comment "TestTechnote". Specifying a different time using -t DATETIME will insert the technote at the specified timestamp location in the timeline. Different technotes can have the same timestamp.
The first argument to create, TECHNOTE-COMMENT, is the title text for the technote that appears in the timeline.
To view all technotes, use the wiki ls command:
fossil wiki ls --technote --show-technote-ids
z739263a134bf0da1d28e939f4c4367f51ef4c51 2020-12-19 13:20:19
e15a918a8bed71c2ac091d74dc397b8d3340d5e1 2018-09-22 17:40:10
A technote ID is the UUID of the technote.
To view an individual technote, use the wiki export command:
fossil wiki export --technote version-2.16
Release Notes 2021-07-02This note describes changes in the Fossil snapshot for ...
The -t|--technote option to the export subcommand takes one of three identifiers: DATETIME; TECHNOTE-ID; and TAG. See the wiki help for specifics.
Users must have check-in privileges (permission "i") in order to create or edit technotes. In addition, users must have create-wiki privilege (permission "f") to create new technotes and edit-wiki privilege (permission "k") in order to edit existing technotes.
Technote content may be formatted as Fossil wiki, Markdown, or a plain text.