Difference between revisions of "Bugslist"

From ProgClub
Jump to: navigation, search
(Created page with "Bugslist is coming!")
 
Line 1: Line 1:
[[Bugslist]] is coming!
+
[[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.

Generated documentation