Svnman

Svnman is the ProgClub Subversion project management software. That's the software that manages creation, maintenance, and release of Subversion projects. For other projects see projects.

Status

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

See tasks for work that still needs to be done.

Motivation

Why this software? Basically to help with project management, particularly around versioning of artefacts.

Administration

Contributors

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

• John Elliot V

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 MIT license.

Components

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

• PHP
• Subversion
• Bugslist

Resources

Downloads

There are presently no tarballs.

Source code

The repository can be browsed online:

https://www.progclub.org/pcrepo/svnman/trunk

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

https://www.progclub.org/svn/pcrepo/svnman/trunk

Or if you want the latest version for development purposes:

https://www.progclub.org/svn/pcrepo/svnman/branches/1.0

Links

• Apache Subversion
• Version Control with Subversion

Specifications

Functional specification

The functional specification describes what the project does.

The software provides a system command with various subcommands for administering projects in a Subversion repository. Supported commands are:

alias

alias: usage: svnman alias [ARG...]

Configure an svnman repository alias. A repository alias associates a repo name with a repo path, allowing the repo name to be used as a shortcut for the repo path in commands with accept a --repo argument. A default working base folder and a ViewVC URL can also be associated with a repo name.

Required arguments:

 --repo-name NAME    : the repository alias
 --repo-path PATH    : the repository path

Optional arguments:

 --working-base PATH : location of working copy base
 --viewvc URL        : URL for ViewVC for repo

create

create: usage: svnman create [ARG...]

Create a new project in a Subversion repository.

Required arguments:

 --project-name NAME : name of the project
 --repo PATH|NAME    : repository to create project in

Optional arguments:

 --project-code CODE : project code (lowercase)
 --project-const     : project const (uppercase)
 --working-base PATH : location of working copy base (working copy parent)
 --working-copy PATH : location of working copy
 --checkout          : checkout into working copy [default]
 --no-checkout       : don't checkout into working copy
 --phpbom            : use the PHPBOM library
 --no-phpbom         : don't use the PHPBOM library [default]

maint

maint: usage: svnman maint [DIR...]

Run maintenance on DIR. Maintenance includes optional code generation and updating of patch version. You should run this before your commits.

freeze

freeze: usage: svnman freeze [DIR...]

Freeze external subprojects in DIR. Only available for projects that aren't in 'tags'. When fronzen externals are pinned to the revision which was current at the time of freezing.

unfreeze

unfreeze: usage: svnman unfreeze [DIR...]

Unfreeze external subprojects in DIR. Only available for projects that aren't in 'tags'. When unfronzen externals are unpinned from a specific revision.

release

release: usage: svnman release [ARG...] [DIR...]

Release a project in DIR. Prior to release projects are frozen, and after release they are unfrozen.

Optional arguments:

 --trunk       : trunk is updated
 --no-trunk    : trunk is not updated
 --auto-trunk  : trunk is updated if project is on latest branch [default]

bump-minor

bump-minor: usage: svnman bump-minor [DIR...]

Create a new version branch from DIR, incrementing the minor version number.

bump-major

bump-major: usage: svnman bump-major [DIR...]

Create a new version branch from DIR, incrementing the major version number.

browse

browse: usage: svnman browse [DIR...]

Open ViewVC in web browser for project in DIR. This requires ViewVC to be configured with repo alias.

gen-doc

gen-doc: usage: svnman gen-doc

Generates documentation for use in the project wiki:

 https://www.progclub.org/wiki/Svnman

Technical specification

The technical specification describes how the project works.

The software is written in PHP and shells out to the 'svn' command-line utility.

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:

This software presumes that the Subversion project has the typical base directories:

• trunk
• branches
• tags

However, we don't use 'trunk' for development. Instead development happens in $major.$minor version branches. So version 0.3 is developed in 'branches/0.3' and version 1.0 is developed in 'branches/1.0'. When a version branch is released by this script 'trunk' can optionally be updated. Within tags the latest $major.$minor versions are maintained under 'tags/latest/$major.$minor' and releases are tagged under 'tags/release/$major/$minor/$patch'.

In order to run svnman you should create an svnman symlink somewhere in your $PATH and point it to bin/svnman.php, something like this:

$ ln -s /path/to/svnman/bin/svnman.php svnman

Notes for developers

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

$ svn co https://www.progclub.org/pcrepo/svnman/branches/1.0 svnman-1.0

Notes for ProgClub administrators

To release a version of this project use the software itself.

First, generate the documentation:

$ bin/dev/gen-doc.sh

Then make sure your working copy is committed:

$ svn ci --message 'Work, work...'

Then run the release:

$ bin/dev/release.sh

You will be prompted to update the project documentation.

Tasks

TODO

MEDIUM

• TODO: bin/dev/gen.sh: 9: generate tasks.wiki with TODO and Done sections...
• TODO: inc/lib.php: 2012: this needs better reporting. Some colour coding would be nice too.
• TODO: inc/lib.php: 2015: need to support other version file formats. Especially *.sh and *.ini formats.
• TODO: inc/lib.php: 2018: make DEBUG a command-line option, not a constant.
• TODO: inc/lib.php: 2020: add a 'latest' subcommand that reports if the current branch is the latest and if not what is.
• TODO: inc/lib.php: 2027: add support for 'browse' subcommand.
• TODO: inc/lib.php: 2029: add support for 'fix-version' subcommand. Will increment even patch version to odd number.
• TODO: inc/lib.php: 2032: clean up after ourselves, delete temp files and directories...
• TODO: inc/lib.php: 2035: add support for --tarball generation during release.
• TODO: inc/lib.php: 2037: improve the documentation.

LOW

• THINK: inc/lib.php: 2023: do we want an optional argument --version-file for manually nominating the version file..? (At the moment we prefer convention over configuration.)

Done

Stuff that's done. Latest stuff on top.

• JE 2020-02-23: created project page
• JE 2020-02-23: released v1.0