|
|
(3 intermediate revisions by the same user not shown) |
Line 1: |
Line 1: |
| bugslist.php is [[User:Sixsigma|John]]'s TODO list management script. If you use this script you might be interested in [https://www.progclub.net/~jj5/timestamp/ ProgClub Timestamp] so you can copy/paste the comment label syntax, or configure KDE so you don't have to. For other projects see [[projects]].
| | [[Bugslist]] has moved to ProgClub: https://www.progclub.org/wiki/bugslist |
| | |
| = Status =
| |
| | |
| [[#Version|Released]]! But there's [[#Work|work]] to do.
| |
| | |
| == Version ==
| |
| | |
| bugslist.php v0.1.1488
| |
| | |
| Copyright © 2016-2017 [https://www.jj5.net/ John Elliot V]
| |
| License GPLv3+: [https://gnu.org/licenses/gpl.html GNU GPL] version 3 or later.
| |
| This is [https://www.gnu.org/philosophy/free-sw.html free software]: you are free to change and redistribute it.
| |
| There is NO WARRANTY, to the extent permitted by law.
| |
| | |
| === Version control info ===
| |
| | |
| Timestamp.......: 2017-03-12 17:38:30 +1100 (Sun, 12 Mar 2017)
| |
| UTC timestamp...: 2017-03-12 06:38:30Z
| |
| Date............: 2017-03-12
| |
| Time............: 17:38:30
| |
| Author..........: [https://www.jj5.net/ jj5]
| |
| File............: bugslist.php
| |
| Revision........: 1488
| |
| URL.............: [https://svn.jj5.net/svn/public/jjrepo/jj5-bin/trunk/bin/bugslist.d/bugslist.php bugslist.php]
| |
| | |
| = Administration =
| |
| | |
| == Contributors ==
| |
| | |
| People who have contributed to this project. Newest on top.
| |
| | |
| * [[User:Sixsigma|John Elliot V]]
| |
| | |
| == Copyright ==
| |
| | |
| Copyright © 2016, [[#Contributors|Contributors]].
| |
| | |
| == License ==
| |
| | |
| Licensed under the [https://gnu.org/licenses/gpl.html GNU GPL] version 3 or later.
| |
| | |
| = Resources =
| |
| | |
| == Source code ==
| |
| | |
| You can [https://svn.jj5.net/jjrepo/jj5-bin/trunk/bin/bugslist.d/bugslist.php read the source code].
| |
| | |
| You can [https://svn.jj5.net/jjrepo/jj5-bin/trunk/bin/bugslist.d browse the repository].
| |
| | |
| You can [https://svn.jj5.net/svn/public/jjrepo/jj5-bin/tags/latest/bin/bugslist.d/bugslist.php checkout the latest stable script], or the [https://svn.jj5.net/svn/public/jjrepo/jj5-bin/tags/latest/bin/bugslist.d full stable system] (including tests and release scripts).
| |
| | |
| You can [https://svn.jj5.net/svn/public/jjrepo/jj5-bin/trunk/bin/bugslist.d/bugslist.php checkout the latest development script], or the [https://svn.jj5.net/svn/public/jjrepo/jj5-bin/trunk/bin/bugslist.d full development system] (including tests and release scripts).
| |
| | |
| == Links ==
| |
| | |
| * [https://svn.jj5.net/jjrepo/jj5-bin/trunk/bin/bugslist.d/bugslist.php?pathrev=1489#l13 bugslist.php]: [https://www.jj5.net/sixsigma/Bugslist.php bugslist.php home page]
| |
| * [https://svn.jj5.net/jjrepo/jj5-bin/trunk/bin/bugslist.d/bugslist.php?pathrev=1489#l91 bugslist.php]: [https://php.net/manual/en/function.assert.php PHP assert()]
| |
| * [https://svn.jj5.net/jjrepo/jj5-bin/trunk/bin/bugslist.d/bugslist.php?pathrev=1489#l99 bugslist.php]: [http://php.net/manual/en/function.set-exception-handler.php PHP set_exception_handler()]
| |
| * [https://svn.jj5.net/jjrepo/jj5-bin/trunk/bin/bugslist.d/bugslist.php?pathrev=1489#l103 bugslist.php]: [http://php.net/manual/en/function.set-error-handler.php PHP set_error_handler()]
| |
| * [https://svn.jj5.net/jjrepo/jj5-bin/trunk/bin/bugslist.d/bugslist.php?pathrev=1489#l4875 bugslist.php]: [http://php.net/manual/en/function.preg-match.php PHP preg_match()]
| |
| * [https://svn.jj5.net/jjrepo/jj5-bin/trunk/bin/bugslist.d/bugslist.php?pathrev=1489#l5086 bugslist.php]: [http://php.net/manual/en/errorfunc.constants.php PHP error constants]
| |
| | |
| == 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][:!] TEXT
| |
| For example: 2017-03-12 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 must be suffixed with punctuation, either ':' or
| |
| '!'. The TEXT follows until the end of the line and on to subsequent lines too.
| |
| | |
| ==== Item types ====
| |
| | |
| The following item types are supported in comment labels:
| |
| | |
| Type................: Description..............................: Priority..:
| |
| Red-flags..........:
| |
| WARNING...........: something to be careful of...............: HIGH
| |
| TEMP..............: a note for code that should be removed...: HIGH
| |
| Stuff to do........:
| |
| BUG...............: something that needs to be fixed.........: HIGH
| |
| TEST..............: something that needs to be tested........: HIGH
| |
| TODO..............: something that needs to be done..........: MEDIUM
| |
| FIXME............: a HIGH priority alias for TODO...........: HIGH
| |
| NICE.............: a LOW priority alias for TODO............: LOW
| |
| HACK..............: something that needs to be improved......: LOW
| |
| CONSIDER..........: something to consider or think about.....: LOW
| |
| THINK............: an alias for CONSIDER....................: LOW
| |
| Stuff that's done..:
| |
| FIXED.............: a BUG that has been fixed................: HIGH
| |
| DONE..............: something that has been done.............: MEDIUM
| |
| COMMIT............: a VCS commit log.........................: LOW
| |
| Notes..............:
| |
| REFERENCE.........: a reference, e.g. a URL..................: LOW
| |
| REF..............: an alias for REFERENCE...................: LOW
| |
| SEE..............: an alias for REFERENCE...................: LOW
| |
| NOTE..............: notes, or items without a label..........: LOW
| |
| DEBUG.............: an item for debugging purposes...........: DEBUG
| |
| | |
| ==== 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, BUG, TEST, FIXME, FIXED
| |
| 2: M: MEDIUM: TODO, DONE
| |
| 3: L: LOW: HACK, COMMIT, REFERENCE, NOTE, NICE, CONSIDER
| |
| 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: <nowiki><!-- --></nowiki>
| |
| Perl #.......: comment labels begin after '# ' (the space is important)
| |
| C/CSS........: comment labels are within: /* */
| |
| | |
| === Program options ===
| |
| | |
| ==== File-system options ====
| |
| | |
| -p, --path=PATH process files in PATH, current directory if omitted
| |
| -f, --file=LIST process files in comma-separated LIST, relative to PATH
| |
| -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=REGEXES comma-separated list of regexes for paths to skip
| |
| -k, --keep=REGEXES comma-separated list of regexes for paths to keep
| |
| ** BE VERY CAREFUL **
| |
| Case sensitive expressions. Use '^' to match start of
| |
| path, '$' to match end of path, etc.
| |
| Note: keeps override skips
| |
| | |
| ==== Filtering options ====
| |
| | |
| -u, --user=[[#USER|USER]] include items for USER
| |
| -d, --date=[[#DATE|DATE]] include items for DATE
| |
| --today include items for today only (default if not debugging)
| |
| --yesterday include items for yesterday only
| |
| -t, --type=[[#TYPE|TYPE]] include items by type, will affect report order.
| |
| Duplicates are ignored.
| |
| -y, --priority=[[#PRIORITY|PRIORITY]] include items with particular PRIORITY.
| |
| --all report on all users, dates, types, and priorities.
| |
| | |
| ==== Reporting options ====
| |
| | |
| -a, --aggregate=[[#FIELD|FIELD]] report aggregation. Duplicates are ignored.
| |
| A heading is printed for each aggregated field.
| |
| -c, --collate=[[#FIELD|FIELD]] report sorting. Duplicates are ignored.
| |
| Default sorting uses binary comparision rather than
| |
| locale sensitive comparison which is probably what
| |
| you want. For --aggregate and --collate uppercase
| |
| FIELD sorts descending.
| |
| e.g. 'dUp' selects by date, user desc, and path
| |
| -h, --heading=[[#FORMAT|FORMAT]]
| |
| heading format options. Duplicates are ignored.
| |
| -o, --output=[[#FIELD|FIELD]]|[[#FORMAT|FORMAT]]|[[#OPTIONS|OPTIONS]]
| |
| report output options. Duplicates are ignored.
| |
| -l, --level level of heading to start at (default 2)
| |
| --na output 'N/A' when no report data
| |
| +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
| |
| --web-help open documentation in Firefox
| |
| --version display version information and exit
| |
| +V, --vcs parse version control (Subversion) logs
| |
| +D, --debug some handy defaults, when debugging or not
| |
| +X, --exit exit without reporting (useful with --show-stats)
| |
| | |
| === Format specifications ===
| |
| | |
| ==== USER ====
| |
| | |
| USER is comma-separated list of usernames.
| |
| Use '*' for all users; '?' for current user.
| |
| | |
| ==== 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.
| |
| Use '*' for all dates.
| |
| | |
| ==== TYPE ====
| |
| | |
| TYPE is a string of abbreviations or comma-separated list of item types.
| |
| Supported types are:
| |
| Red-flags:
| |
| w: WARNING....: something to be careful of
| |
| m: TEMP.......: a note for code that should be removed
| |
| Stuff to do:
| |
| b: BUG........: something that needs to be fixed
| |
| e: TEST.......: something that needs to be tested
| |
| t: TODO.......: something that needs to be done
| |
| h: HACK.......: something that needs to be improved
| |
| c: CONSIDER...: something to consider
| |
| Stuff that's done:
| |
| f: FIXED......: a BUG that has been fixed
| |
| d: DONE.......: something that has been done
| |
| v: COMMIT.....: a VCS commit log
| |
| Notes:
| |
| r: REFERENCE..: a reference, e.g. a URL
| |
| s: REFERENCE..:
| |
| n: NOTE.......: notes, or items without a label
| |
| g: DEBUG......: an item for debugging purposes
| |
| e.g. 'TODO, NOTE' or 'bht' for 'BUG, HACK, TODO'
| |
| Use '*' for all types.
| |
| | |
| ==== PRIORITY ====
| |
| | |
| PRIORITY is a comma-separeted list of priorities or a range of priorities
| |
| indicated with a dash '-' between a low and a high priority.
| |
| A priority can be indicated by a priority number, a priority letter or
| |
| abbreviation, or a priority name. Use '*' for all priorities.
| |
| Supported values are:
| |
| #: Abbr: Name...:
| |
| 0: C, !: CRITICAL
| |
| 1: H: HIGH
| |
| 2: M: MEDIUM
| |
| 3: L: LOW
| |
| 4: D: DEBUG
| |
| | |
| ==== FIELD ====
| |
| | |
| FIELD is a string of abbreviations or comma-separated list of fields.
| |
| Supported fields are:
| |
| u: user: select username
| |
| d: date: select date
| |
| g: long date: select date in long format
| |
| t: type: select item type
| |
| y: priority: select item priority
| |
| e: filemtime: select file modification timestamp
| |
| b: both: select path and file
| |
| p: path: select path
| |
| f: file: select file, do not prefix path.
| |
| This may not be what you want, may merge
| |
| files from different directories.
| |
| l: line: select line number
| |
| m: name: select file name
| |
| k: link: select link to file (for specific revision)
| |
| s: reference: select reference (or text if not REFERENCE)
| |
| i: initials: select Wiki initials initials (requires config)
| |
| n: new-lines: select number of new lines
| |
| o: old-lines: select number of old lines
| |
| c: line-diff: select lines difference
| |
| r: revision: select VCS revision number
| |
| w: code: select work code
| |
| x: text: select item text
| |
| | |
| ==== FORMAT ====
| |
| | |
| FORMAT is a string of abbreviations or comma-separated list of format
| |
| options.
| |
| Supported format options are:
| |
| U: plain-user: don't format user
| |
| D: plain-date: don't format date
| |
| T: plain-type: don't format type
| |
| Y: plain-priority: don't format priority
| |
| E: plain-filemtime: don't format filemtime
| |
| B: plain-both: don't format path/file
| |
| P: plain-path: don't format path
| |
| F: plain-file: don't format file
| |
| L: plain-line: don't format line
| |
| M: plain-name: don't format name
| |
| K: plain-link: don't format link
| |
| S: plain-reference: don't format reference
| |
| I: plain-initials: don't format initials
| |
| N: plain-new-lines: don't format new lines
| |
| O: plain-old-lines: don't format old lines
| |
| C: plain-line-diff: don't format line diff
| |
| R: plain-revision: don't format VCS revision number
| |
| W: plain-code: don't format work code
| |
| X: plain-text: don't format item text
| |
| e.g. 'UT' disables formatting for user and type values.
| |
| | |
| ==== OPTIONS ====
| |
| | |
| OPTIONS is a string of abbreviations or comma-separated list of report
| |
| options.
| |
| Supported report options are:
| |
| h: html: output to HTML instead of wiki text
| |
| a: table: output to HTML/wiki table instead of list
| |
| e.g. 'ha' selects HTML with tables
| |
| | |
| === Feedback ===
| |
| | |
| Report bugs to: [mailto:jj5@progclub.org?subject=bugslist.php jj5@progclub.org]
| |
| | |
| = Specifications =
| |
| | |
| == Functional specification ==
| |
| | |
| See [[#Help|help]] for information about how the script is supposed to work.
| |
| | |
| == 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 [mailto:jj5@progclub.org?subject=bugslist.php 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 [mailto:jj5@progclub.org?subject=bugslist.php jj5@progclub.org] along with a statement that you are willing to be listed in the [[bugslist.php#Contributors|contributors]] section of the documentation and willing to license your contribution under the [[bugslist.php#License|license]].
| |
| | |
| For security reasons write access to [https://svn.jj5.net/jjrepo/ jjrepo] is only available for [[User:Sixsigma|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 [https://www.progclub.org/ ProgClub] and [https://www.progclub.org/wiki/Register register]?
| |