README.md (8681B)
1 # NAME 2 3 piknik - Issue tracking using CLI 4 5 # SYNOPSIS 6 7 **piknik** add \[ -d store_dir \] \[ \--alias issue_alias \] caption 8 9 **piknik** show \[ -i issue_id \] \[ -d store_dir \] \[ -r renderer \] 10 \[ \--state state \] 11 12 **piknik** show \[ -d store_dir \] -r html \[ -o output_dir \] 13 14 **piknik** mod \< -i issue_id \> \[ -d store_dir \] \[ \--state state 15 \] \[ -t tag \] \[ -u tag \] \[ \--dep issue_id \] \[ \--undep issue_id 16 \] \[ \--assign id \] \[ \--unassign id \] 17 18 **piknik** mod \< -i issue_id \> \[ -d store_dir \] \[ \--block \] 19 20 **piknik** mod \< -i issue_id \> \[ -d store_dir \] \[ \--unblock \] 21 22 **piknik** comment \< -i issue_id \> \[ -d store_dir \] \[ \[ -x \"text 23 content\" \... \] \[ -y file \... \] \... \] 24 25 # DESCRIPTION 26 27 This tool enables issue tracking by command line interface. 28 29 After an issue has been created it can move through different 30 pre-defined, kanban-like states. They can also be tagged, assigned and 31 commented on. 32 33 # COMMANDS 34 35 The following commands are available: 36 37 > **show** - Output all issues for all or selected issue states. 38 > 39 > **add** - Propose a new issue. 40 > 41 > **mod** - Tag, assign, set dependencies and modify state of an 42 > existing issue. 43 > 44 > **comment** - Add comment to an existing issue. 45 46 ## Common options 47 48 **-d** 49 50 : Issue state store directory. 51 52 **-h** 53 54 **\--help** Command help summary. 55 56 **-i***issue_id* 57 58 **\--issue-id***issue_id* Issue to operate on. Argument can be issue 59 alias or full issue uuid. Only available with **mod** and **comment**. 60 61 **-s***state* 62 63 **\--state***state* Limit output to issue having the given *state*. 64 (Only valid with **show** or **mod**). 65 66 -v 67 68 : Write debugging log to standard error. 69 70 ## Options for add 71 72 **\--alias** 73 74 : Specify alias used to refer to issue when using **-i**. If not 75 specified, an alias will be auto-generated. See **ALIAS**. Only 76 available with **add**. 77 78 ## Options for show 79 80 **-f** 81 82 **\--files** Save attachments to filesystem. Can be used in the context 83 of viewing details of a single issue, or in conjunction with **-r html 84 -o**. Only available with **show**. 85 86 **-o***dir* 87 88 **\--files-dir***dir* Output issue details to individual files in *dir*. 89 Only available with **show -r html \...**. 90 91 **-r***format* 92 93 **\--renderer***format* Output format. Valid values are *plain* and 94 *html*. 95 96 **-reverse** 97 98 : Sort comments with oldest first. Only available with **show**. 99 100 **\--show-finished** 101 102 : Include issues with state **FINISHED** in output. Only available 103 with **show**. 104 105 ## Options for mod 106 107 **\--assign***key_id* 108 109 : Assign the issue to entity defined by *key_id*. If it is the first 110 assignment for an issue, the assigned will become the issue *owner* 111 (see **\--owner** and **ACTIONS/Assignment** below. Only available 112 with **mod**. 113 114 **\--block** 115 116 : Set the **BLOCKED** state on the issue. Preserves the previous 117 state; a following **\--unblock** instruction will return the issue 118 to the pre-blocked state. Only available with **mod**. 119 120 **\--dep***issue_id* 121 122 : Make the current issue (identified by **-i** dependent on 123 *issue_id*. Only available with **mod**. 124 125 **\--owner***key_id* 126 127 : Set the entity represented by *key_id* as issue owner. 128 129 **-t***tag* 130 131 **\--tag***tag* Add the given tag to the issue. Only available with 132 **mod**. 133 134 **\--unassign***key_id* 135 136 : Remove the assignment of the issue to entity defined by *key_id*. 137 Only available with **mod**. 138 139 **\--unblock** 140 141 : Remove block on issue. Will return the issue to its previous state 142 (before the block). Only available with **mod**. 143 144 **\--undep***issue_id* 145 146 : Remove dependency on *issue_id*. Only available with **mod**. 147 148 **-u***tag* 149 150 **\--untag***tag* Remove the given tag from the issue. Only available 151 with **mod**. 152 153 ## Options for comment 154 155 **-s***pgp_key_fingerprint* 156 157 **\--sign-as***pgp_key_fingerprint* Use the private key matching the 158 fingerprint to sign (instead of the default key). Only available with 159 **comment**. 160 161 **-x***text* 162 163 **\--text***text* Add a text content part to the comment. Must be 164 enclosed by double quotes. Only available with **comment**. 165 166 **-y***file* 167 168 **\--file***file* Add file as content part to the comment. Can be any 169 type of file. Only available with **comment**. See the **COMMENT** 170 section for more information. 171 172 # STATES 173 174 The tracking of the issue lifetime is organized using a pre-defined set 175 of kanban-like states. 176 177 **PROPOSED** 178 179 : The initial state of an issue after being created by **piknik add**. 180 Is intended for review by issue board moderator. 181 182 **BACKLOG** 183 184 : The initial state of an issue after being \"accepted\" by a 185 moderator. 186 187 **PENDING** 188 189 : An issue has been queued for imminent processing. 190 191 **DOING** 192 193 : An issue is currently being worked on. 194 195 **REVIEW** 196 197 : Work that was done on an issue is currently in review. 198 199 **BLOCKED** 200 201 : Progress on a **PENDING** issue is currently not possible. 202 203 **FINISHED** 204 205 : Processing of an issue has been completed. 206 207 # ACTIONS 208 209 ## Assignment 210 211 Indicates an individual or entity that is responsible for processing the 212 issue. 213 214 Currently assigments are defined as hexadecimal values. By convention, 215 the value should correspond to e.g. a public key or a key fingerprint 216 (e.g. PGP). **piknik** will check that the value is hexadecimal, but 217 will not do additional verification. 218 219 The first assigned entity to an issue automatically becomes the issue 220 owner. The issue ownership may be changed using **\--owner**, but 221 ownership cannot be removed entirely after the initial assignment. 222 223 ## Tagging 224 225 Any issue may be assigned any number of tags. Tags may be added and 226 removed individually. 227 228 ## Dependencies 229 230 Any issue may be set as dependent on another issue. Dependencies may be 231 set or unset. Dependencies must be manually managed, and will not be 232 magically removed as a side-effect of state transitions. 233 234 # COMMENTING 235 236 Comments are stored as email-like Multipart MIME message logs. They may 237 include any number of plaintext and file attachment parts intermingled. 238 239 All comments must be **signed** using a PGP key. Unless the **-s** flag 240 is used, the default signing key will be used. It is currently not 241 possible to comment without a PGP key. 242 243 # RENDERING 244 245 There are currently two rendering options for displaying issue indices 246 and individual issue details, *plain* (plain text) and *html*. 247 Ideosyncracies for each are described below. 248 249 ## PLAIN 250 251 When listing the issue index, output will be in the form: 252 253 [STATE] 254 <caption> <tags> <uuid> [(alias)] 255 256 Per-issue render should be self-explanatory. 257 258 ## HTML 259 260 If rendered with **-o** *outdir* it creates a browseable version of 261 individual issues from the issue index in the specified directory. 262 263 Some image types will by default be displayed inline. There is currently 264 no way to toggle this behavior. 265 266 # EXAMPLE 267 268 This example illustrates a possible lifetime of an issue. 269 270 # propose new issue 271 piknik add Title describing the issue --alias myissue 272 273 # accept proposed issue (move to backlog state) 274 piknik mod -i myissue --accept 275 276 # move the issue to state "DOING" 277 piknik mod -i myissue --state doing 278 279 # tag the issue as a "BUG" 280 piknik mod -i myissue --tag bug 281 282 # Add a signed text comment to the issue 283 piknik comment -i myissue -x "This is a text comment" 284 285 # Add a comment with intermixed text and attachment contents to the issue 286 piknik comment -i myissue -x "This is a text comment with two attachments " -y attachment.png -y another.pdf -x "This text follows the attachments" 287 288 # Write index of all issues as plain text to standard output 289 piknik show 290 291 # Write issue details as plain text to standard output 292 piknik show -i myissue 293 294 # Write index of all issues as html to standard output 295 piknik show --render html 296 297 # Write index and individual issue as browseable html to directory "outdir" 298 piknik show --render html -o outdir 299 300 # Mark issue as finished 301 piknik mod -i myissue --finish 302 303 # KNOWN ISSUES 304 305 Currently issues are tracked using - in fact - **piknik**. An HTML 306 (read-only) render can be found at 307 [](https://holbrook.no/issues/piknik)https://holbrook.no/issues/piknik 308 309 # LICENSE 310 311 This documentation and its source is licensed under the Creative Commons 312 Attribution-Sharealike 4.0 International license. 313 314 The source code of the tool this documentation describes is licensed 315 under the GNU General Public License 3.0. 316 317 # COPYRIGHT AND CONTACT 318 319 [Louis Holbrook](mailto:dev@holbrook.no) 320 321 [](https://holbrook.no)https://holbrook.no 322 323 PGP: 59A844A484AC11253D3A3E9DCDCBD24DD1D0E001 324 325 # SOURCE CODE 326 327 https://git.defalsify.org/piknik 328 329 330 # ABOUT THIS DOCUMENT 331 332 This document was generated using `pandoc -f man -t markdown ...`