Bugslist: Difference between revisions
Jump to navigation
Jump to search
(→Help: updating help...) |
(→Help: updating help...) |
||
| Line 227: | Line 227: | ||
=== Feedback === | === Feedback === | ||
Report bugs to: [mailto:jj5@progclub.org?subject=bugslist.php jj5@progclub.org | Report bugs to: [mailto:jj5@progclub.org?subject=bugslist.php jj5@progclub.org] | ||
== Source code == | == Source code == | ||
Revision as of 23:57, 10 December 2016
bugslist.php is John's TODO list management script. For other projects see projects.
Status
Released! But there's stuff TODO.
Version
bugslist.php v0.1.1066
Copyright © 2016 John Elliot V License GPLv3+: GNU GPL version 3 or later. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.
Version control info
Timestamp.......: 2016-12-11 00:47:15 +1100 (Sun, 11 Dec 2016) UTC timestamp...: 2016-12-10 13:47:15Z Date............: 2016-12-11 Time............: 00:47:15 Author..........: jj5 File............: bugslist.php Revision........: 1066 URL.............: bugslist.php
Administration
Contributors
People who have contributed to this project. Newest on top.
Copyright
Copyright © 2016, Contributors.
License
Licensed under the GNU GPL version 3 or later.
Resources
Help
Usage: php path/to/bugslist.php [OPTION]... This is a source code processing and reporting tool to help with software development project management. It processes files in the specified directory and matches special comment syntax to get notes and work items which it then reports on. Output reports are in MediaWiki wiki text syntax designed to be included in your project wiki.
Comment label syntax
The heart of bugslist.php is the comment label syntax you use in your source code. It's basically: DATE USER DASH TYPE[PRIORITY][PUNCTUATION] TEXT For example: 2016-12-11 jj5 - HACK[HIGH]: expedient, you say? The date is in ISO format, the user must be a valid UNIX user, and the dash is just to try and limit false positives. The TYPE indicates what sort of item this is; it can be one of the types listed below. Your type can be suffixed with an optional priority within square brackets. After the optional priority your type can be suffixed with various PUNCTUATION, e.g.: '!', '...', '.', ':', ';', '-'. The TEXT follows until the end of the line and on to subsequent lines too.
Item priority
You can use a priority number, priority letter, or priority name to indicate a priority: #: Abbr: Name: Default: 0: C, !: CRITICAL: N/A 1: H: HIGH: WARNING, TEMP 2: M: MEDIUM: BUG, TODO 3: L: LOW: DONE, HACK, NOTE, REF 4: D: DEBUG: DEBUG
Comment syntax
Comment syntax for various programming languges is supported: Plain text...: comment labels begin at the first character on the line C++, etc //..: comment labels begin after '// ' (the space is important) HTML/XML.....: comment labels are within: Perl #.......: comment labels begin after '# ' (the space is important) C/CSS........: comment labels are within: /* */
Filtering options
-u, --user=USER include items for USER
USER is comma-separated list of usernames
-d, --date=DATE include items for DATE
DATE is ISO formatted date prefix, e.g.:
'2016' for all items in 2016,
'2016-01' for items in Jan 2016,
'2016-,01,02' for items in Jan/Feb 2016,
'2016-01-,01,02' for items on 1st/2nd Jan 2106,
'2016-01-02,2016-01-04' for 2nd/4th Jan 2016.
-t, --types=[TYPES|ALIAS] include items by type, will affect report order.
Note: you can have duplicates, if you wish.
TYPES is comma-separated list of item types:
TODO......: something that needs to be done
DONE......: something that has been done
NOTE......: notes, or items without a label
BUG.......: something that needs to be fixed
HACK......: something that needs to be improved
WARNING...: something to be careful of
REF.......: a reference, usually a URL (alias SEE)
TEMP......: a note that should be removed
DEBUG.....: an item for debugging purposes
e.g. 'TODO, NOTE'
ALIAS is string of type aliases:
t: TODO
d: DONE
n: NOTE
b: BUG
h: HACK
w: WARNING
r: REF
m: TEMP
z: DEBUG
e.g. 'bht' is 'BUG, HACK, TODO'
-y, --priority=[PRIORITIES] include items with particular PRIORITIES. Can
be priority number, priority letter/abbreviation, or
priority name.
File-system options
-p, --path=PATH process files in PATH, current directory if omitted
-i, --include=EXTENSIONS comma-separated list of included file extensions
-e, --exclude=EXTENSIONS comma-separated list of excluded file extensions
Note: excludes override includes. This is useful when
you want to exclude missing extensions () which
are included by default.
-s, --skip=DIRS comma-separated list of directory paths to skip
-k, --keep=DIRS comma-separated list of directory paths to keep
** BE VERY CAREFUL **
e.g.:
'bin,obj' matches 'p/t/colbbin' and 'p/t/my-obj'
'/bin,/obj' matches 'path/to/bin' and 'path/to/obj'
a warning is emitted for DIRS with no leading '/'
Note: keeps override skips
Output options
-r, --report=REPORT report aggregation. Duplicates are not supported.
REPORT is a string of abbreviations or comma-separated
list of report fields.
Supported report fields are:
user: group by user
date: group by date
type: group by item type
priority: group by item priority
path: group by path
file: group by file (prefixes path if not grouped
by path)
merge: group by file, do not prefix path.
This may not be what you want, will merge
files from different directories.
Supported abbreviations are:
u: user
d: date
t: type
y: priority
p: path
f: file
m: merge
Use uppercase abbreviations to sort descending.
Default sorting uses binary comparision rather than
locale sensitive comparison which is probably what
you want.
e.g. 'dUp' reports by date, user desc, and path
-o, --options=OPTIONS
report options. Duplicates are not supported.
OPTIONS is a string of abbreviations or
comma-separated list of report options.
Supported options are:
user: include username in output
date: include date in output
type: include type in output
path: include path in output
file: include file in output
line: include line number in output
text: includes text in output (default)
html: output to HTML instead of wiki text
table: output to HTML/wiki table instead of list
no-user-link: don't create hyperlink for user
no-date-link: don't create hyperlink for date
no-path-link: don't create hyperlink for path
no-file-link: don't create hyperlink for file
no-line-link: don't create hyperlink for line
Supported abbreviations are:
u: user
d: date
t: type
p: path
f: file
l: line
x: text
U: no-user-link
D: no-date-link
P: no-path-link
F: no-file-link
L: no-line-link
h: html
a: table
e.g. 'dtx' selects date, type, and text.
+N, --natural use locale sensitive sorting instead of binary sorting
+B, --binary use binary sorting (This is the default. Redundant? :)
+Q, --quiet disable warnings, stats, and progress on stderr
+S, --show-stats enable statistics report on stderr
-S, --hide-stats disable statistics report on stderr (default)
+P, --show-progress enable progress report on stderr
-P, --hide-progress disable progress report on stderr (default)
+O, --show-options report on user options on stderr
-O, --hide-options disable user options report (default)
+W, --show-warnings report warnings on stderr (default)
-W, --hide-warnings disable warnings
Other options
--help display this help text and exit -v, --version display version information and exit +D, --debug some handy defaults, when debugging or not
Feedback
Report bugs to: jj5@progclub.org
Source code
The repository can be browsed online:
The latest stable released version of the code is available via Subversion from:
Or if you want the latest version for development purposes:
Links
N/A
Specifications
Functional specification
Technical specification
The script is a PHP CLI script.
Notes
Notes for implementers
If you are interested in incorporating this software into your project, here's what you need to know:
Just copy-and-paste your way to victory! Feel free to ask questions.
Notes for developers
If you're interested in contributing to this software, here's what you need to know:
Send your patch to jj5@jj5.net along with a statement that you are willing to be listed in the contributors section of the documentation and willing to license your contribution under the license.
For security reasons write access to jjrepo is only available for John. It's basically my private repository. If you'd like to hack on projects where you do have checkin permissions on the Subversion repository, along with infrastructure for running your code, then why not head over to ProgClub and register?
Release notes
Release notes are (supposed to be) added after notable releases are made. New release notes are added to the bottom of the release notes section and have a level 3 title based on the release date.
Tasks
TODO
Things to do, in rough order of priority:
- fix this TODO list.
Done
Stuff that's done. Latest stuff goes on the bottom of the list.
2016-12-10
- JE: created project page and initial documentation.