Difference between revisions of "Bugslist"

From ProgClub
Jump to: navigation, search
(15 intermediate revisions by the same user not shown)
Line 78: Line 78:
 
The script is a [[#PHP|PHP]] CLI script (tested on PHP v7.2). It shells out to [[#Subversion|Subversion]] for some of its functionality.
 
The script is a [[#PHP|PHP]] CLI script (tested on PHP v7.2). It shells out to [[#Subversion|Subversion]] for some of its functionality.
  
= Miscellanea =
+
= Notes =
 +
 
 +
See [[versioning]] for information on our semantic version numbers.
 +
 
 +
== Notes for implementers ==
  
== Subversion ==
+
If you are interested in incorporating this software into your project, here's what you need to know.
  
The [[bugslist]] software makes use of the [https://en.wikipedia.org/wiki/Subversion Subversion] command-line interface. If Subversion is not installed then [[bugslist]] may not work!
+
=== Installation ===
  
== ViewVC ==
+
This software has been developed and tested on [[#Ubuntu|Ubuntu 18.04 LTS]] GNU/Linux. It will probably work in other Unix environments and it will definitely be broken on Windows. (If you'd like to make it work on Windows we will accept your patch!)
  
The [http://www.viewvc.org/ ViewVC] software can be used for browsing a [[#Subversion|Subversion]] repository via the web. We support ViewVC integration (via the config file).
+
After you [[#Dependency installation|install dependencies]] you need to decide if you want to install for [[#User installation|just your user]] or for an [[#System installation|entire system]].
  
== PHP ==
+
After you've installed [[bugslist]] swing by the [https://www.progclub.net/~jj5/timestamp/ ProgClub Timestamp] utility for some documentation concerning KDE shortcut key config to help you enter [[bugslist]] compatible comments in your code.
  
The [[bugslist]] software is written mostly in the [https://www.php.net/ PHP programming language] which <nowiki>we^H^H</nowiki>[[User:John|I]] love! :)
+
==== Dependency installation ====
  
Other bits and pieces are done with [[#Subversion|Subversion]] and [[#BASH|BASH]].
+
In order to run [[bugslist]] you might also need to install some dependencies, if so do that first:
  
== Ubuntu ==
+
$ <code>sudo apt install php-cli subversion</code>
  
This software was developed and tested on [https://en.wikipedia.org/wiki/Ubuntu Ubuntu] 18.04 LTS.
+
==== System installation ====
  
== $PATH ==
+
After you [[#Dependency installation|install dependencies]] you can install [[bugslist]] for an entire system with these two commands:
  
When you [[#Installation|install]] [[bugslist]] you should make sure a symlink to <code>bin/svnman.php</code> is in your $PATH [https://en.wikipedia.org/wiki/Environment_variable environment variable].
+
$ <code>sudo svn checkout https://www.progclub.org/svn/pcrepo/bugslist/trunk /usr/local/lib/bugslist</code>
 +
$ <code>sudo ln -s /usr/local/lib/bugslist/bin/bugslist.php /usr/local/bin/bugslist</code>
  
= Notes =
+
===== System upgrade =====
  
See [[versioning]] for information on our semantic version numbers.
+
If you've done a [[#System installation|system installation]] you can do a system upgrade like this:
  
== Notes for implementers ==
+
$ <code>sudo svn up /usr/local/lib/bugslist</code>
  
If you are interested in incorporating this software into your project, here's what you need to know.
+
==== User installation ====
  
=== Installation ===
+
First make sure you've [[#Dependency installation|installed the dependencies]].
  
 
The recommended way to install this software is by checking out the 'trunk' version from source control.
 
The recommended way to install this software is by checking out the 'trunk' version from source control.
Line 123: Line 128:
 
  $ <code>ln -s ~/software/bugslist/bin/bugslist.php bugslist</code>
 
  $ <code>ln -s ~/software/bugslist/bin/bugslist.php bugslist</code>
  
You might also need to install some dependencies, such as:
+
===== User upgrade =====
  
# <code>apt install php-cli subversion</code>
+
Assuming you followed the [[#User installation|user installation]] instructions you can do a user upgrade something like this:
  
This software has been developed and tested on [[#Ubuntu|Ubuntu 18.04 LTS]] GNU/Linux. It will probably work in other Unix environments and it will definitely be broken on Windows. (If you'd like to make it work on Windows we will accept your patch!)
+
$ <code>svn up ~/software/bugslist</code>
 
 
After you've installed [[bugslist]] swing by the [https://www.progclub.net/~jj5/timestamp/ ProgClub Timestamp] utility for some documentation concerning KDE shortcut key config to help you enter comments in your code.
 
  
 
=== Configuration ===
 
=== Configuration ===
Line 151: Line 154:
 
  # <code>apt install php-cli subversion</code>
 
  # <code>apt install php-cli subversion</code>
  
Send your patch to [mailto:jj5@progclub.org?subject=bugslist jj5@progclub.org] along with a statement that you are willing to be listed in the [[#Contributors|contributors]] section of the documentation and willing to license your contribution under the [[#License|license]].
+
If you have a bugfix or improvement please send your patch to [mailto:jj5@progclub.org?subject=bugslist jj5@progclub.org] along with a statement that you are willing to be listed in the [[#Contributors|contributors]] section of the documentation and willing to license your contribution under the [[#License|license]].
  
 
== Notes for administrators ==
 
== Notes for administrators ==
Line 166: Line 169:
  
 
You will be prompted to update the project documentation.
 
You will be prompted to update the project documentation.
 +
 +
= Miscellanea =
 +
 +
== Subversion ==
 +
 +
The [[bugslist]] software makes use of the [https://en.wikipedia.org/wiki/Subversion Subversion] command-line interface. If Subversion is not installed then [[bugslist]] may not work!
 +
 +
== ViewVC ==
 +
 +
The [http://www.viewvc.org/ ViewVC] software can be used for browsing a [[#Subversion|Subversion]] repository via the web. We support ViewVC integration (via the config file).
 +
 +
== BASH ==
 +
 +
The [https://en.wikipedia.org/wiki/Bash_(Unix_shell) bash] shell is our [https://en.wikipedia.org/wiki/Unix_shell Unix shell] of choice. You don't need Bash to run [[bugslist]] but it is used by our build scripts.
 +
 +
== PHP ==
 +
 +
The [[bugslist]] software is written mostly in the [https://www.php.net/ PHP programming language] which <nowiki>we^H^H</nowiki>[[User:John|I]] love! :)
 +
 +
Other bits and pieces are done with [[#Subversion|Subversion]] and [[#BASH|BASH]].
 +
 +
== Ubuntu ==
 +
 +
This software was developed and tested on [https://en.wikipedia.org/wiki/Ubuntu Ubuntu] 18.04 LTS.
 +
 +
== $PATH ==
 +
 +
When you [[#Installation|install]] [[bugslist]] you should make sure a symlink to <code>[https://www.progclub.org/pcrepo/bugslist/trunk/bin/bugslist.php bin/bugslist.php]</code> is in your $PATH [https://en.wikipedia.org/wiki/Environment_variable environment variable].
  
 
= Generated documentation =
 
= Generated documentation =
Line 171: Line 202:
 
== Help ==
 
== Help ==
  
  '''Usage:''' php path/to/bugslist.php <nowiki>[</nowiki>[[#OPTION|OPTION]]]... <nowiki>[</nowiki>[[#DIR|DIR]]]...
+
  '''Usage:''' php path/to/bugslist.php <nowiki>[</nowiki>[[#OPTION|OPTION]]]... <nowiki>[</nowiki>[[#PATH|PATH]]]...
 
  This is a source code processing and reporting tool to help with software
 
  This is a source code processing and reporting tool to help with software
 
  development project management. It processes files in the specified
 
  development project management. It processes files in the specified
Line 183: Line 214:
 
  source code. It's basically:
 
  source code. It's basically:
 
   [[#DATE|DATE]] [[#USER|USER]] [[#DASH|DASH]] [[#TYPE|TYPE]]<nowiki>[</nowiki>[[#PRIORITY|PRIORITY]]][:!] [[#TEXT|TEXT]]
 
   [[#DATE|DATE]] [[#USER|USER]] [[#DASH|DASH]] [[#TYPE|TYPE]]<nowiki>[</nowiki>[[#PRIORITY|PRIORITY]]][:!] [[#TEXT|TEXT]]
  For example: 2020-03-02 [https://www.jj5.net/ jj5] - [[#HACK|HACK]]<nowiki>[</nowiki>[[#HIGH|HIGH]]]: expedient, you say?
+
  For example: 2020-03-04 [https://www.jj5.net/ jj5] - [[#HACK|HACK]]<nowiki>[</nowiki>[[#HIGH|HIGH]]]: expedient, you say?
 
  The date is in [[#ISO|ISO]] format, the user must be a valid [[#UNIX|UNIX]] user, and the dash
 
  The date is in [[#ISO|ISO]] format, the user must be a valid [[#UNIX|UNIX]] user, and the dash
 
  is just to try and limit false positives. The [[#TYPE|TYPE]] indicates what sort of
 
  is just to try and limit false positives. The [[#TYPE|TYPE]] indicates what sort of
Line 245: Line 276:
 
==== File-system options ====
 
==== File-system options ====
  
-f, [[#--file|--file]]=[[#LIST|LIST]]      process files in comma-separated [[#LIST|LIST]], overrides [[#--path|--path]]
 
-p, [[#--path|--path]]=[[#PATH|PATH]]      process files in [[#PATH|PATH]], current directory if omitted
 
                      Path options can also be passed without a switch.
 
 
  -i, [[#--include|--include]]=[[#EXTENSIONS|EXTENSIONS]]  comma-separated list of included file extensions
 
  -i, [[#--include|--include]]=[[#EXTENSIONS|EXTENSIONS]]  comma-separated list of included file extensions
 
  -e, [[#--exclude|--exclude]]=[[#EXTENSIONS|EXTENSIONS]]  comma-separated list of excluded file extensions
 
  -e, [[#--exclude|--exclude]]=[[#EXTENSIONS|EXTENSIONS]]  comma-separated list of excluded file extensions
Line 470: Line 498:
 
== Links ==
 
== Links ==
  
 +
Generated with [[bugslist]].
 +
 +
* [https://www.progclub.org/pcrepo/bugslist/branches/0.2/bin/bugslist.php#l9 bugslist.php]: [https://www.progclub.org/wiki/Bugslist#Installation Bugslist Installation Guide]
 
* [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l13 bugslist.php]: [https://www.progclub.org/wiki/Bugslist bugslist home page]
 
* [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l13 bugslist.php]: [https://www.progclub.org/wiki/Bugslist bugslist home page]
* [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l96 bugslist.php]: [http://php.net/manual/en/function.set-exception-handler.php [[#PHP|PHP]] set_exception_handler()]
+
* [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l98 bugslist.php]: [http://php.net/manual/en/function.set-exception-handler.php [[#PHP|PHP]] set_exception_handler()]
* [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l100 bugslist.php]: [http://php.net/manual/en/function.set-error-handler.php [[#PHP|PHP]] set_error_handler()]
+
* [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l102 bugslist.php]: [http://php.net/manual/en/function.set-error-handler.php [[#PHP|PHP]] set_error_handler()]
* [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6058 bugslist.php]: [http://php.net/manual/en/function.preg-match.php [[#PHP|PHP]] preg_match()]
+
* [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6070 bugslist.php]: [http://php.net/manual/en/function.preg-match.php [[#PHP|PHP]] preg_match()]
* [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6271 bugslist.php]: [http://php.net/manual/en/errorfunc.constants.php [[#PHP|PHP]] error constants]
+
* [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6299 bugslist.php]: [http://php.net/manual/en/errorfunc.constants.php [[#PHP|PHP]] error constants]
  
 
== [[#TODO|TODO]] list ==
 
== [[#TODO|TODO]] list ==
  
Generated with [[bugslist]]:
+
Generated with [[bugslist]].
  
 
=== [[#HIGH|HIGH]] priority ===
 
=== [[#HIGH|HIGH]] priority ===
  
* [[#BUG|BUG]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6991 bugslist.php]: plain and not-html-encoded need to be separated. They are conflated at the moment. Perhaps a '[[#text|text]]' reporting option..?
+
* [[#BUG|BUG]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6943 bugslist.php]: plain and not-html-encoded need to be separated. They are conflated at the moment. Perhaps a '[[#text|text]]' reporting option..?
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l3901 bugslist.php]: need to check we're not processing svn property changes...
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l3877 bugslist.php]: need to check we're not processing svn property changes...
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l5371 bugslist.php]: it would be better to use strrpos to find the last colon...
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l5362 bugslist.php]: it would be better to use strrpos to find the last colon...
  
 
=== [[#MEDIUM|MEDIUM]] priority ===
 
=== [[#MEDIUM|MEDIUM]] priority ===
  
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l625 bugslist.php]: check if '[[#ods|ods]]' is plain text / [[#XML|XML]] format...
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l655 bugslist.php]: check if '[[#ods|ods]]' is plain text / [[#XML|XML]] format...
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l1368 bugslist.php]: document [[#--max-date|--max-date]]
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l1328 bugslist.php]: document [[#--max-date|--max-date]]
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l1369 bugslist.php]: unit tests for [[#--max-date|--max-date]]
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l1330 bugslist.php]: unit tests for [[#--max-date|--max-date]]
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l1377 bugslist.php]: add [[#--min-date|--min-date]]
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l1339 bugslist.php]: add [[#--min-date|--min-date]]
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l1412 bugslist.php]: implement revision filter
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l1374 bugslist.php]: implement revision filter
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l2843 bugslist.php]: finish support for text output
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l2804 bugslist.php]: finish support for text output
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l2845 bugslist.php]: finish support for Wiki output
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l2806 bugslist.php]: finish support for Wiki output
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l2847 bugslist.php]: add support for [[#HTML|HTML]] output
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l2808 bugslist.php]: add support for [[#HTML|HTML]] output
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l2850 bugslist.php]: add support for [[#HTML|HTML]] lists
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l2811 bugslist.php]: add support for [[#HTML|HTML]] lists
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l2852 bugslist.php]: add support for tables
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l2813 bugslist.php]: add support for tables
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l2991 bugslist.php]: add support for MediaWiki publishing.
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l2952 bugslist.php]: add support for MediaWiki publishing.
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l5454 bugslist.php]: call is_int( $line ) instead. Confirm $line is an integer.
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l5449 bugslist.php]: call is_int( $line ) instead. Confirm $line is an integer.
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l5782 bugslist.php]: [[#HTML|HTML]] table reporting
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l5779 bugslist.php]: [[#HTML|HTML]] table reporting
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l5789 bugslist.php]: [[#HTML|HTML]] list reporting
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l5787 bugslist.php]: [[#HTML|HTML]] list reporting
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l5796 bugslist.php]: wiki table reporting
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l5795 bugslist.php]: wiki table reporting
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l5978 bugslist.php]: check for newlines in value and remove them
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l5984 bugslist.php]: check for newlines in value and remove them
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6939 bugslist.php]: make priority filter and default priority a config file option.
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6862 bugslist.php]: make priority filter and default priority a config file option.
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6942 bugslist.php]: make $file_extension_include, etc. configurable in config file.
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6867 bugslist.php]: make $file_extension_include, etc. configurable in config file.
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6958 bugslist.php]: make config override a command-line option. e.g.
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6890 bugslist.php]: make config override a command-line option. e.g.
 
** [[#--config|--config]]=user,jj5,initials=JE;user,jj5,wiki-user=Sixsigma
 
** [[#--config|--config]]=user,jj5,initials=JE;user,jj5,wiki-user=Sixsigma
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6960 bugslist.php]: ignore extra punctuation after item type/priority
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6893 bugslist.php]: ignore extra punctuation after item type/priority
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6961 bugslist.php]: [[#VCS|VCS]] support should probably include git in addition to svn.
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6895 bugslist.php]: [[#VCS|VCS]] support should probably include git in addition to svn.
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6967 bugslist.php]: test duplicate command-line options
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6903 bugslist.php]: test duplicate command-line options
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6968 bugslist.php]: add better support for multiline svn commit messages
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6905 bugslist.php]: add better support for multiline svn commit messages
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6969 bugslist.php]: update doco about skip/keep now using regular expressions.
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6907 bugslist.php]: update doco about skip/keep now using regular expressions.
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6975 bugslist.php]: change path to prefix '/'
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6917 bugslist.php]: change path to prefix '/'
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6976 bugslist.php]: use &lt;nowiki&gt;''&lt;/nowiki&gt; for ''..? Or henc() item text? Or surround item text in &lt;nowiki&gt;?
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6919 bugslist.php]: use &lt;nowiki&gt;''&lt;/nowiki&gt; for ''..? Or henc() item text? Or surround item text in &lt;nowiki&gt;?
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6978 bugslist.php]: check for '[[#basic|basic]]' regex match and warn if we don't match a proper item. I.e. we might match '//[[#DATE|DATE]] [[#USER|USER]] -' (without space after '//' which will be skipped. We should warn in that case.
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6922 bugslist.php]: check for '[[#basic|basic]]' regex match and warn if we don't match a proper item. I.e. we might match '//[[#DATE|DATE]] [[#USER|USER]] -' (without space after '//' which will be skipped. We should warn in that case.
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6984 bugslist.php]: add support for item age (in days)
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6930 bugslist.php]: add support for item age (in days)
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6985 bugslist.php]: add support for [[#svn:externals|svn:externals]]...
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6932 bugslist.php]: add support for [[#svn:externals|svn:externals]]...
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6986 bugslist.php]: add a dates list report (as an index into e.g. ((MyProject/2016-12-22|2016-12-22)), etc.)
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6934 bugslist.php]: add a dates list report (as an index into e.g. ((MyProject/2016-12-22|2016-12-22)), etc.)
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6988 bugslist.php]: add support for [[#--max-date|--max-date]] and [[#--min-date|--min-date]]
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6937 bugslist.php]: add support for [[#--max-date|--max-date]] and [[#--min-date|--min-date]]
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6989 bugslist.php]: support for [[#START|START]]/[[#END|END]] validation
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6939 bugslist.php]: support for [[#START|START]]/[[#END|END]] validation
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6993 bugslist.php]: prefix item text with 'wiki: ' to flag item as being encoded in wiki text...
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6946 bugslist.php]: prefix item text with 'wiki: ' to flag item as being encoded in wiki text...
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6995 bugslist.php]: add a [[#LOC|LOC]] count feature, by file type, direcoty, etc.
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6949 bugslist.php]: add a [[#LOC|LOC]] count feature, by file type, direcoty, etc.
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6996 bugslist.php]: detected [[#VCS|VCS]] could be svn *and* git... use an array.
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6951 bugslist.php]: detected [[#VCS|VCS]] could be svn *and* git... use an array.
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6997 bugslist.php]: match [[#START|START]]/[[#END|END]] notes, warn mismatch, and ignore them.
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6953 bugslist.php]: match [[#START|START]]/[[#END|END]] notes, warn mismatch, and ignore them.
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6998 bugslist.php]: add support for '[[#[[#NEW|NEW]]|[[#NEW|NEW]]]]' notes for patches
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6955 bugslist.php]: add support for '[[#[[#NEW|NEW]]|[[#NEW|NEW]]]]' notes for patches
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6999 bugslist.php]: add support for '[[#[[#OLD|OLD]]|[[#OLD|OLD]]]]' notes for removals
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6957 bugslist.php]: add support for '[[#[[#OLD|OLD]]|[[#OLD|OLD]]]]' notes for removals
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l7000 bugslist.php]: match {[[#NEW|NEW]],[[#OLD|OLD]]}/[[#END|END]] notes
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6959 bugslist.php]: match {[[#NEW|NEW]],[[#OLD|OLD]]}/[[#END|END]] notes
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l7001 bugslist.php]: [[#--text|--text]], [[#--html|--html]], [[#--wiki|--wiki]] output modes
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6961 bugslist.php]: [[#--text|--text]], [[#--html|--html]], [[#--wiki|--wiki]] output modes
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l7002 bugslist.php]: [[#--list|--list]], [[#--table|--table]] formatting options
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6963 bugslist.php]: [[#--list|--list]], [[#--table|--table]] formatting options
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l7003 bugslist.php]: add support for a '[[#[[#UPGRADE|UPGRADE]]|[[#UPGRADE|UPGRADE]]]]' type which are things that need to be reviewed on upgrade.
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6965 bugslist.php]: add support for a '[[#[[#UPGRADE|UPGRADE]]|[[#UPGRADE|UPGRADE]]]]' type which are things that need to be reviewed on upgrade.
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l7006 bugslist.php]: get rid of -p and -f options and just process all files/directories nominated on the command line.
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6968 bugslist.php]: get rid of -p and -f options and just process all files/directories nominated on the command line.
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l7009 bugslist.php]: need to improve the wiki documentation, at the moment there are a lot of broken internal links to missing content. We probably need to add a 'gen-doc' feature to the bugslist command.
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6971 bugslist.php]: need to improve the wiki documentation, at the moment there are a lot of broken internal links to missing content. We probably need to add a 'gen-doc' feature to the bugslist command.
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l7013 bugslist.php]: we should make sure that bugslist can run even if the '[[#svn|svn]]' executable is missing.
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6975 bugslist.php]: we should make sure that bugslist can run even if the '[[#svn|svn]]' executable is missing.
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/test/args/run.sh#l928 run.sh]: plain-* output options
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/test/args/run.sh#l877 run.sh]: plain-* output options
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/test/args/run.sh#l1062 run.sh]: test [[#--na|--na]] and -o=X and -o=g
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/test/args/run.sh#l1011 run.sh]: test [[#--na|--na]] and -o=X and -o=g
 
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/test/vcs-type/run.sh#l5 run.sh]: review this test and re-enable it if it's useful.
 
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/test/vcs-type/run.sh#l5 run.sh]: review this test and re-enable it if it's useful.
  
 
=== [[#LOW|LOW]] priority ===
 
=== [[#LOW|LOW]] priority ===
  
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l3748 bugslist.php]: not sure if a little sleep for a few milliseconds is helpful or not..? Should do some benchmarking...
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l3721 bugslist.php]: not sure if a little sleep for a few milliseconds is helpful or not..? Should do some benchmarking...
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6944 bugslist.php]: linting for invalid comment labels, e.g. [[#HAKK|HAKK]], missing/invalid punctuation, etc.
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6870 bugslist.php]: linting for invalid comment labels, e.g. [[#HAKK|HAKK]], missing/invalid punctuation, etc.
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6949 bugslist.php]: MediaWiki integration would be nice. I.e. automatically insert reports into the MediaWiki database. Might be smarter to go in through the front-end via [[#HTTP|HTTP]] (need [[#HTTP|HTTP]] auth and a valid cookie for that... doable.)
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6878 bugslist.php]: MediaWiki integration would be nice. I.e. automatically insert reports into the MediaWiki database. Might be smarter to go in through the front-end via [[#HTTP|HTTP]] (need [[#HTTP|HTTP]] auth and a valid cookie for that... doable.)
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6971 bugslist.php]: add revision range filters, e.g. -r=50:100
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6910 bugslist.php]: add revision range filters, e.g. -r=50:100
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6972 bugslist.php]: renumber user exit levels to list file-system stuff before filters stuff.
+
* [[#TODO|TODO]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6912 bugslist.php]: renumber user exit levels to list file-system stuff before filters stuff.
* [[#HACK|HACK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l3729 bugslist.php]: we just bail if previous revision is zero.
+
* [[#HACK|HACK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l3698 bugslist.php]: we just bail if previous revision is zero.
* [[#HACK|HACK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l5360 bugslist.php]: We haven't verfied the syntax of the [[#URL|URL]], and it might require [[#HTML|HTML]] encoding?
+
* [[#HACK|HACK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l5350 bugslist.php]: We haven't verfied the syntax of the [[#URL|URL]], and it might require [[#HTML|HTML]] encoding?
* [[#HACK|HACK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l5378 bugslist.php]: We haven't verfied the syntax of the [[#URL|URL]], and it might require [[#HTML|HTML]] encoding?
+
* [[#HACK|HACK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l5371 bugslist.php]: We haven't verfied the syntax of the [[#URL|URL]], and it might require [[#HTML|HTML]] encoding?
* [[#HACK|HACK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l5390 bugslist.php]: OK, so if we ask to report references on items which are not references we will just report the item text:
+
* [[#HACK|HACK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l5384 bugslist.php]: OK, so if we ask to report references on items which are not references we will just report the item text:
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l371 bugslist.php]: do we want either of these..?
+
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l390 bugslist.php]: do we want either of these..?
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l387 bugslist.php]: make [[#DEBUG|DEBUG]] '[[#x|x]]' or '[[#z|z]]'..?
+
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l409 bugslist.php]: make [[#DEBUG|DEBUG]] '[[#x|x]]' or '[[#z|z]]'..?
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l419 bugslist.php]: maybe default [[#CONSIDER|CONSIDER]] to [[#MEDIUM|MEDIUM]]..?
+
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l443 bugslist.php]: maybe default [[#CONSIDER|CONSIDER]] to [[#MEDIUM|MEDIUM]]..?
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l463 bugslist.php]: consider support for '[[#Z|Z]]' =&gt; '[[#[[#DEBUG|DEBUG]]|[[#DEBUG|DEBUG]]]]'..?
+
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l491 bugslist.php]: consider support for '[[#Z|Z]]' =&gt; '[[#[[#DEBUG|DEBUG]]|[[#DEBUG|DEBUG]]]]'..?
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l624 bugslist.php]: consider if '[[#phar|phar]]' should be included...
+
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l653 bugslist.php]: consider if '[[#phar|phar]]' should be included...
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l635 bugslist.php]: consider if '[[#properties|properties]]' should be excluded...
+
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l668 bugslist.php]: consider if '[[#properties|properties]]' should be excluded...
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l636 bugslist.php]: consider if '[[#xcf|xcf]]' should be excluded...
+
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l670 bugslist.php]: consider if '[[#xcf|xcf]]' should be excluded...
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l660 bugslist.php]: does $proc_descriptor need to be a global..?
+
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l683 bugslist.php]: does $proc_descriptor need to be a global..?
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l4857 bugslist.php]: would it be better to scan for nested [[#TODO|TODO]] items when $type is finished {[[#FIXED|FIXED]],[[#DONE|DONE]],[[#COMMIT|COMMIT]]} and associate the details with the finished item..?
+
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l4836 bugslist.php]: would it be better to scan for nested [[#TODO|TODO]] items when $type is finished {[[#FIXED|FIXED]],[[#DONE|DONE]],[[#COMMIT|COMMIT]]} and associate the details with the finished item..?
 
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l5877 bugslist.php]: make null headings a command-line/config option? At the moment null headings are skipped, not reported.
 
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l5877 bugslist.php]: make null headings a command-line/config option? At the moment null headings are skipped, not reported.
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6396 bugslist.php]: is this what we want..?
+
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6427 bugslist.php]: is this what we want..?
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6941 bugslist.php]: alias '[[#[[#TASK|TASK]]|[[#TASK|TASK]]]]' to '[[#[[#TODO|TODO]]|[[#TODO|TODO]]]]'..?
+
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6865 bugslist.php]: alias '[[#[[#TASK|TASK]]|[[#TASK|TASK]]]]' to '[[#[[#TODO|TODO]]|[[#TODO|TODO]]]]'..?
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6946 bugslist.php]: add support for [[#FEATURE|FEATURE]]/[[#IMPROVEMENT|IMPROVEMENT]] items..?
+
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6873 bugslist.php]: add support for [[#FEATURE|FEATURE]]/[[#IMPROVEMENT|IMPROVEMENT]] items..?
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6947 bugslist.php]: add support for ';' list delimiters in addition to ','..?
+
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6875 bugslist.php]: add support for ';' list delimiters in addition to ','..?
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6953 bugslist.php]: add support for multiple reports delimited with ';'..?
+
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6883 bugslist.php]: add support for multiple reports delimited with ';'..?
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6955 bugslist.php]: add [[#MAINT|MAINT]] type w/ [[#--maint|--maint]] option to report on maintenance gotchas? (i.e. stuff you need to know about for doing a release etc.)
+
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6886 bugslist.php]: add [[#MAINT|MAINT]] type w/ [[#--maint|--maint]] option to report on maintenance gotchas? (i.e. stuff you need to know about for doing a release etc.)
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6963 bugslist.php]: for svn items is the line number '[[#svn|svn]]' or is it the first changed line in the associated file? (2016-12-15 [https://www.jj5.net/ jj5]: I think the line number is the revision number, which is handy if we sort by line.)
+
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6898 bugslist.php]: for svn items is the line number '[[#svn|svn]]' or is it the first changed line in the associated file? (2016-12-15 [https://www.jj5.net/ jj5]: I think the line number is the revision number, which is handy if we sort by line.)
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6974 bugslist.php]: add '[[#[[#SOON|SOON]]|[[#SOON|SOON]]]]' item type?
+
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6915 bugslist.php]: add '[[#[[#SOON|SOON]]|[[#SOON|SOON]]]]' item type?
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6981 bugslist.php]: add [[#BUGREF|BUGREF]] type, for references to include in [[#BUG|BUG]] reports..? At the moment we've just extended [[#BUG|BUG]] to include an optional [[#URL|URL]]...
+
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6926 bugslist.php]: add [[#BUGREF|BUGREF]] type, for references to include in [[#BUG|BUG]] reports..? At the moment we've just extended [[#BUG|BUG]] to include an optional [[#URL|URL]]...
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6990 bugslist.php]: remove [[#START|START]]/[[#END|END]] notes from notes..?
+
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6941 bugslist.php]: remove [[#START|START]]/[[#END|END]] notes from notes..?
 +
* [[#THINK|THINK]]: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/src/code/bugslist.php#l6978 bugslist.php]: do we wanna skip symlinks when processing..?

Revision as of 13:30, 7 March 2020

Bugslist is the ProgClub TODO list management software. That's the software that generates a TODO list from the comments in your source code. If you use this script you might be interested in 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.

Status

We use semantic versioning. Latest production version: 0.2. Latest development version: 0.2.

See the TODO list for work that still needs to be done.

Motivation

Why this software? This is so that we can put TODO notes in our source code where they're most relevant and convenient but also publish a TODO list on the wiki and in our documentation.

Administration

Contributors

Members who have contributed to this project. Newest on top.

All contributors have agreed to the terms of the Contributor License Agreement. This excludes any upstream contributors who tend to have different administrative frameworks.

Copyright

Copyright © 2020, Contributors.

License

Licensed under the GPL.

Components

Libraries, tools, services or media from third parties used under license:

Resources

Downloads

There are presently no tarballs. Running an `svn checkout` against the ProgClub Subversion repository (pcrepo) is the recommended way to install this software. See the Installation Guide for details.

Source code

The source code can be browsed online:

The most interesting code is here:

The latest stable (read-only) released version of the code is available from Subversion here:

Or if you want the latest version for development purposes:

Note that our software development is done on the version branch, not on trunk. We use trunk to track the latest stable release.

Specifications

Functional specification

The functional specification describes what the project does.

See help for information about how the script is supposed to work.

Technical specification

The technical specification describes how the project works.

The script is a PHP CLI script (tested on PHP v7.2). It shells out to Subversion for some of its functionality.

Notes

See versioning for information on our semantic version numbers.

Notes for implementers

If you are interested in incorporating this software into your project, here's what you need to know.

Installation

This software has been developed and tested on Ubuntu 18.04 LTS GNU/Linux. It will probably work in other Unix environments and it will definitely be broken on Windows. (If you'd like to make it work on Windows we will accept your patch!)

After you install dependencies you need to decide if you want to install for just your user or for an entire system.

After you've installed bugslist swing by the ProgClub Timestamp utility for some documentation concerning KDE shortcut key config to help you enter bugslist compatible comments in your code.

Dependency installation

In order to run bugslist you might also need to install some dependencies, if so do that first:

$ sudo apt install php-cli subversion

System installation

After you install dependencies you can install bugslist for an entire system with these two commands:

$ sudo svn checkout https://www.progclub.org/svn/pcrepo/bugslist/trunk /usr/local/lib/bugslist
$ sudo ln -s /usr/local/lib/bugslist/bin/bugslist.php /usr/local/bin/bugslist
System upgrade

If you've done a system installation you can do a system upgrade like this:

$ sudo svn up /usr/local/lib/bugslist

User installation

First make sure you've installed the dependencies.

The recommended way to install this software is by checking out the 'trunk' version from source control.

In order to run bugslist you should create a bugslist symlink somewhere in your $PATH and point it to bin/bugslist.php.

So a full installation might look something like this:

$ cd ~/software
$ svn checkout https://www.progclub.org/svn/pcrepo/bugslist/trunk bugslist
$ cd ~/bin
$ ln -s ~/software/bugslist/bin/bugslist.php bugslist
User upgrade

Assuming you followed the user installation instructions you can do a user upgrade something like this:

$ svn up ~/software/bugslist

Configuration

After you install bugslist you might like to configure one or more projects. Create a config file called etc/bugslist.php under the directory you will run bugslist in. See etc/bugslist-example.php for an example.

Notes for developers

If you're looking to set up a development environment for this project here's what you need to know:

Get the latest code from the version branch:

$ svn checkout https://www.progclub.org/svn/pcrepo/bugslist/branches/0.2 bugslist-0.2

You can then run the unit tests like this:

$ cd bugslist-0.2 && bin/test/test.sh

Note that you may need to install some dependencies, such as:

# apt install php-cli subversion

If you have a bugfix or improvement please send your patch to jj5@progclub.org 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.

Notes for administrators

To release a version of this project use svnman.

First, run maintenance and commit any changes:

$ svnman commit

Then run the release:

$ bin/dev/release.sh

You will be prompted to update the project documentation.

Miscellanea

Subversion

The bugslist software makes use of the Subversion command-line interface. If Subversion is not installed then bugslist may not work!

ViewVC

The ViewVC software can be used for browsing a Subversion repository via the web. We support ViewVC integration (via the config file).

BASH

The bash shell is our Unix shell of choice. You don't need Bash to run bugslist but it is used by our build scripts.

PHP

The bugslist software is written mostly in the PHP programming language which we^H^HI love! :)

Other bits and pieces are done with Subversion and BASH.

Ubuntu

This software was developed and tested on Ubuntu 18.04 LTS.

$PATH

When you install bugslist you should make sure a symlink to bin/bugslist.php is in your $PATH environment variable.

Generated documentation

Help

Usage: php path/to/bugslist.php [OPTION]... [PATH]...
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 is the comment label syntax you use in your
source code. It's basically:
  DATE USER DASH TYPE[PRIORITY][:!] TEXT
For example: 2020-03-04 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..........:
  TEMP..............: a note for code that should be removed...: HIGH
 Stuff to do........:
  BUG...............: something that needs to be fixed.........: 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
  TEST..............: something that needs to be tested........: MEDIUM
  HACK..............: something that needs to be improved......: LOW
  THINK.............: something to consider or think about.....: LOW
   CONSIDER.........: an alias for THINK.......................: 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..............:
  WARNING...........: something to be careful of...............: HIGH
  REFERENCE.........: a reference, e.g. a URL..................: MEDIUM
   REF..............: an alias for REFERENCE...................: MEDIUM
   SEE..............: an alias for REFERENCE...................: MEDIUM
  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:    X:     NEXT:  N/A
  1: !, C: CRITICAL:  N/A
  2:    H:     HIGH:  TEMP, BUG, FIXME, FIXED, WARNING
  3:    M:   MEDIUM:  TODO, TEST, DONE, REFERENCE[REF|SEE]
  4:    L:      LOW:  NICE, HACK, THINK[CONSIDER], COMMIT, NOTE
  9:    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: /* */
  Bind, INI....: comment labels begin after '; ' (the space is important)

Program options

File-system options

-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       include items for USER
-d, --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       include items by type, will affect report order.
                      Duplicates are ignored.
-y, --priority=PRIORITY  include items with particular PRIORITY.
    --all             report on all users, dates, types, and priorities.
    --none            don't report matches (stats only).

Reporting options

-a, --aggregate=FIELD report aggregation. Duplicates are ignored.
                      A heading is printed for each aggregated field.
-c, --collate=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
                      heading format options. Duplicates are ignored.
-o, --output=FIELD|FORMAT
                      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)
+C, --show-loc        enable lines of code report on stderr
-C, --hide-loc        disable lines of code report on stderr (default)
+T, --show-ext        enable file type report on stderr
-T, --hide-ext        disable file type 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

Formatting options

   --text             output as plain-text (default)
                      // 2017-06-06 jj5 - TODO: finish support for text output
   --wiki             output as MediaWiki wiki-text
                      // 2017-06-06 jj5 - TODO: finish support for Wiki output
   --html             output as HTML
                      // 2017-06-06 jj5 - TODO: add support for HTML output
   --list             output as list (default)
                      // 2017-06-06 jj5 - TODO: add support for HTML lists
   --table            output as table (instead of list)
                      // 2017-06-06 jj5 - TODO: add support for tables

Count options

    --items           print the total number of items and exit
    --tasks           print the total number of tasks and exit
    --fixes           print the total number of fixes and exit
    --features        print the total number of features and exit
    --commits         print the total number of commits and exit
    --notes           print the total number of notes and exit

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 etc)
-w, --slow=MICROTIME  process items slowly (delay MICROTIME per file)
-m, --publish=PUBNAME publish output to a MediaWiki wiki (requires config).
                      Think 'm' for 'subMit'...
    --unknown         display list of unknown file extensions then exit

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:
   m: TEMP.......: a note for code that should be removed
  Stuff to do:
   b: BUG........: something that needs to be fixed
   t: TODO.......: something that needs to be done
   e: TEST.......: something that needs to be tested
   h: HACK.......: something that needs to be improved
   c: THINK......: something to consider or think about
  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:
   w: WARNING....: something to be careful of
   r: REFERENCE..: a reference, e.g. a URL
   s: REFERENCE..: an alias for 'r'
   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:    X:     NEXT
  1: !, C: CRITICAL
  2:    H:     HIGH
  3:    M:   MEDIUM
  4:    L:      LOW
  9:    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.

PUBNAME

 PUBNAME is string that represents the publishing options to use.
   These options must be configured in the config file.
 // 2017-06-06 jj5 - TODO: add support for MediaWiki publishing.

MediaWiki integration

For proper wikitable support edit MediaWiki:Common.css and add:
   .right td { text-align: right; }
   .right td:first-child { text-align: left; }

Feedback

Report bugs to: jj5@progclub.org

Links

Generated with bugslist.

TODO list

Generated with bugslist.

HIGH priority

  • BUG: bugslist.php: plain and not-html-encoded need to be separated. They are conflated at the moment. Perhaps a 'text' reporting option..?
  • TODO: bugslist.php: need to check we're not processing svn property changes...
  • TODO: bugslist.php: it would be better to use strrpos to find the last colon...

MEDIUM priority

LOW priority