|
1
|
<title>Technical Notes</title> |
|
2
|
|
|
3
|
<h2>What Is A "Technote"?</h2> |
|
4
|
|
|
5
|
In Fossil, a "technical note" or "technote" (formerly called an "event") |
|
6
|
is a special kind of [./wikitheory.wiki | wiki page] |
|
7
|
that is associated with a point in time rather than having a page name. |
|
8
|
Each technote causes a single entry to appear on the |
|
9
|
[/timeline?y=e | Timeline Page]. |
|
10
|
Clicking on the timeline link will display the text of the technote. |
|
11
|
The wiki content, the timeline entry text, the |
|
12
|
time of the technote, and the timeline background color can all be edited. |
|
13
|
|
|
14
|
As with check-ins, wiki, and tickets, all technotes automatically synchronize |
|
15
|
to other repositories. Hence, technotes can be viewed, created, and edited |
|
16
|
off-line. And the complete edit history for technotes is maintained |
|
17
|
for auditing purposes. |
|
18
|
|
|
19
|
Possible uses for technotes include: |
|
20
|
|
|
21
|
* <b>Milestones</b>. Project milestones, such as releases or beta-test |
|
22
|
cycles, can be recorded as technotes. The timeline entry for the technote |
|
23
|
can be something simple like "Version 1.2.3" perhaps with a bright |
|
24
|
color background to draw attention to the entry and the wiki content |
|
25
|
can contain release notes, for example. |
|
26
|
|
|
27
|
* <b>Blog Entries</b>. Blog entries from developers describing the current |
|
28
|
state of a project, or rationale for various design decisions, or |
|
29
|
roadmaps for future development, can be entered as technotes. |
|
30
|
|
|
31
|
* <b>Process Checkpoints</b>. For projects that have a formal process, |
|
32
|
technotes can be used to record the completion or the initiation of |
|
33
|
various process steps. For example, a technote can be used to record |
|
34
|
the successful completion of a long-running test, perhaps with |
|
35
|
performance results and details of where the test was run and who |
|
36
|
ran it recorded in the wiki content. The technote can be added |
|
37
|
from a script. |
|
38
|
|
|
39
|
* <b>News Articles</b>. Significant occurrences in the life cycle of |
|
40
|
a project can be recorded as news articles using technotes. Perhaps the |
|
41
|
domain name of the canonical website for a project changes, or new |
|
42
|
server hardware is obtained. Such happenings are appropriate for |
|
43
|
reporting as news. |
|
44
|
|
|
45
|
* <b>Announcements</b>. Changes to the composition of the development |
|
46
|
team or acquisition of new project sponsors can be communicated as |
|
47
|
announcements which can be implemented as technotes. |
|
48
|
|
|
49
|
* <b>Signed Checksums</b>. Technotes containing cryptographically signed |
|
50
|
checksums can be linked to repository artifacts, thereby creating a |
|
51
|
traceable, auditable chain so that users can readily verify the integrity |
|
52
|
and authenticity of project deliverables. And the command line interface |
|
53
|
to technotes enables embedding such processes in scripts. |
|
54
|
|
|
55
|
No project is required to use technotes. But technotes can help many projects |
|
56
|
stay better organized and provide a better historical record of the |
|
57
|
development progress. |
|
58
|
|
|
59
|
<h2>Viewing Technotes</h2> |
|
60
|
|
|
61
|
Because technotes are considered a special kind of wiki, |
|
62
|
users must have permission to read wiki in order read technotes. |
|
63
|
Enable the "j" permission under the /Setup/Users menu in order |
|
64
|
to give specific users or user classes the ability to view wiki |
|
65
|
and technotes. |
|
66
|
|
|
67
|
Technotes show up on the timeline. Click on the hyperlink beside the |
|
68
|
technote title to see the complete text. |
|
69
|
|
|
70
|
<h2>Creating, Editing and Viewing Technotes</h2> |
|
71
|
|
|
72
|
There is a hyperlink under the /wikihelp menu that can be used to create |
|
73
|
new technotes. And there is a submenu hyperlink on technote displays for |
|
74
|
editing existing technotes. |
|
75
|
|
|
76
|
Technotes can also be created using the <b>wiki create</b> command: |
|
77
|
|
|
78
|
<verbatim> |
|
79
|
fossil wiki create TestTechnote -t now --technote-bgcolor lightgreen technote.md |
|
80
|
Created new tech note 2021-03-15 13:05:56 |
|
81
|
</verbatim> |
|
82
|
|
|
83
|
This command inserts a light green technote in the timeline at 2021-03-15 13:05:56, with |
|
84
|
the contents of file <b>technote.md</b> and comment "TestTechnote". Specifying a different time using |
|
85
|
<b>-t DATETIME</b> will insert the technote at the specified timestamp location in the timeline. |
|
86
|
Different technotes can have the same timestamp. |
|
87
|
|
|
88
|
The first argument to create, <b>TECHNOTE-COMMENT</b>, is the title text for the technote |
|
89
|
that appears in the timeline. |
|
90
|
|
|
91
|
To view all technotes, use the <b>wiki ls</b> command: |
|
92
|
|
|
93
|
<verbatim> |
|
94
|
fossil wiki ls --technote --show-technote-ids |
|
95
|
z739263a134bf0da1d28e939f4c4367f51ef4c51 2020-12-19 13:20:19 |
|
96
|
e15a918a8bed71c2ac091d74dc397b8d3340d5e1 2018-09-22 17:40:10 |
|
97
|
</verbatim> |
|
98
|
|
|
99
|
A technote ID is the UUID of the technote. |
|
100
|
|
|
101
|
To view an individual technote, use the <b>wiki export</b> command: |
|
102
|
|
|
103
|
<verbatim> |
|
104
|
fossil wiki export --technote version-2.16 |
|
105
|
Release Notes 2021-07-02 |
|
106
|
|
|
107
|
This note describes changes in the Fossil snapshot for ... |
|
108
|
</verbatim> |
|
109
|
|
|
110
|
The <b>-t|--technote</b> option to the <b>export</b> subcommand takes one of |
|
111
|
three identifiers: <b>DATETIME</b>; <b>TECHNOTE-ID</b>; and <b>TAG</b>. |
|
112
|
See the [/help/wiki | wiki help] for specifics. |
|
113
|
|
|
114
|
Users must have check-in privileges (permission "i") in order to |
|
115
|
create or edit technotes. In addition, users must have create-wiki |
|
116
|
privilege (permission "f") to create new technotes and edit-wiki |
|
117
|
privilege (permission "k") in order to edit existing technotes. |
|
118
|
|
|
119
|
Technote content may be formatted as [/wiki_rules | Fossil wiki], |
|
120
|
[/md_rules | Markdown], or plain text. |
|
121
|
|