Difference between revisions of "Bugslist"
(Created page with "Bugslist is coming!") |
|||
Line 1: | Line 1: | ||
− | [[Bugslist]] is | + | [[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 [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]]. |
+ | |||
+ | = Status = | ||
+ | |||
+ | We use [[Versioning|semantic versioning]]. | ||
+ | Latest production version: [https://www.progclub.org/pcrepo/bugslist/tags/latest/0.2/ 0.2]. | ||
+ | Latest development version: [https://www.progclub.org/pcrepo/bugslist/branches/0.2/ 0.2]. | ||
+ | |||
+ | See [[#TODO|TODO]] 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 but also publish a [[#TODO|TODO]] list on the wiki and in our documentation. | ||
+ | |||
+ | = Administration = | ||
+ | |||
+ | == Contributors == | ||
+ | |||
+ | Members who have contributed to this project. Newest on top. | ||
+ | |||
+ | * [[User:John|John Elliot V]] | ||
+ | |||
+ | All contributors have agreed to the terms of the [[ProgClub:Copyrights#ProgClub_projects|Contributor License Agreement]]. This excludes any upstream contributors who tend to have different administrative frameworks. | ||
+ | |||
+ | == Copyright == | ||
+ | |||
+ | Copyright © 2020, [[#Contributors|Contributors]]. | ||
+ | |||
+ | == License == | ||
+ | |||
+ | Licensed under the [[GPL]]. | ||
+ | |||
+ | == Components == | ||
+ | |||
+ | Libraries, tools, services or media from third parties used under license: | ||
+ | |||
+ | * [[#PHP|PHP]] | ||
+ | * [[#Subversion|Subversion]] | ||
+ | |||
+ | = Resources = | ||
+ | |||
+ | == Downloads == | ||
+ | |||
+ | There are presently no tarballs. Running an `svn checkout` against the [[ProgClub]] [[#Subversion|Subversion]] repository ([[pcrepo]]) is the recommended way to install this software. See the [[#Installation|Installation Guide]] for details. | ||
+ | |||
+ | == Source code == | ||
+ | |||
+ | The source code can be browsed online: | ||
+ | |||
+ | * https://www.progclub.org/pcrepo/bugslist/trunk | ||
+ | |||
+ | The most interesting code is here: | ||
+ | |||
+ | * https://www.progclub.org/pcrepo/bugslist/trunk/src/code/bugslist.php | ||
+ | |||
+ | The latest stable (read-only) released version of the code is available from Subversion here: | ||
+ | |||
+ | * https://www.progclub.org/svn/pcrepo/bugslist/trunk | ||
+ | |||
+ | Or if you want the latest version for development purposes: | ||
+ | |||
+ | * https://www.progclub.org/svn/pcrepo/bugslist/branches/0.2 | ||
+ | |||
+ | Note that our software development is done on the [[#Version branches|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|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|Subversion]] for some of its functionality. | ||
+ | |||
+ | = 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). | ||
+ | |||
+ | == PHP == | ||
+ | |||
+ | The [[svnman]] 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 [[#JSON|JSON]], [[#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]] [[svnman]] 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]. | ||
+ | |||
+ | = 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 === | ||
+ | |||
+ | 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 <code>bugslist</code> symlink somewhere in your [[#$PATH|$PATH]] and point it to <code>bin/bugslist.php</code>. | ||
+ | |||
+ | So a full installation might look something like this: | ||
+ | |||
+ | $ <code>cd ~/software</code> | ||
+ | $ <code>svn checkout https://www.progclub.org/svn/pcrepo/bugslist/trunk bugslist</code> | ||
+ | $ <code>cd ~/bin</code> | ||
+ | $ <code>ln -s ~/software/bugslist/bin/bugslist.php bugslist</code> | ||
+ | |||
+ | You might also need to install some dependencies, such as: | ||
+ | |||
+ | # <code>apt install php-cli subversion</code> | ||
+ | |||
+ | 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!) | ||
+ | |||
+ | === Configuration === | ||
+ | |||
+ | After you install [[bugslist]] you might like to configure one or more projects. Create a config file called <code>etc/bugslist.php</code> under the directory you will run bugslist from. See <code>[https://www.progclub.org/pcrepo/bugslist/branches/0.2/etc/bugslist-example.php etc/bugslist-example.php]</code> 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: | ||
+ | |||
+ | $ <code>svn checkout https://www.progclub.org/svn/pcrepo/bugslist/branches/0.2 bugslist-0.2</code> | ||
+ | |||
+ | You can then run the unit tests like this: | ||
+ | |||
+ | $ <code>cd bugslist-0.2 && bin/test/test.sh</code> | ||
+ | |||
+ | Note that you may need to install some dependencies, such as: | ||
+ | |||
+ | # <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]]. | ||
+ | |||
+ | == Notes for administrators == | ||
+ | |||
+ | To release a version of this project use the software itself. | ||
+ | |||
+ | First, run maintenance and commit any changes: | ||
+ | |||
+ | $ <code>svnman commit</code> | ||
+ | |||
+ | Then run the release: | ||
+ | |||
+ | $ <code>bin/dev/release.sh</code> | ||
+ | |||
+ | You will be prompted to update the project documentation. | ||
+ | |||
+ | = Generated documentation = |
Revision as of 17:26, 2 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 TODO 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 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.
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).
PHP
The svnman software is written mostly in the PHP programming language which we^H^HI love! :)
Other bits and pieces are done with JSON, Subversion, and BASH.
Ubuntu
This software was developed and tested on Ubuntu 18.04 LTS.
$PATH
When you install svnman you should make sure a symlink to bin/svnman.php
is in your $PATH environment variable.
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
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
You might also need to install some dependencies, such as:
# apt install php-cli subversion
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!)
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 from. 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
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 the software itself.
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.