Difference between revisions of "Svnman"
Line 82: | Line 82: | ||
= Command-line interface = | = Command-line interface = | ||
− | general usage: svnman [[#SUBCOMMAND|SUBCOMMAND]] <nowiki>[</nowiki>[[#ARG|ARG]]...] <nowiki>[</nowiki>[[#DIR|DIR]]...] | + | general usage: svnman [[#SUBCOMMAND|SUBCOMMAND]] <nowiki>[</nowiki>[[#ARG|ARG]]...] <nowiki>[</nowiki>[[#DIR|DIR]]...] |
− | A Subversion project management tool. | + | A Subversion project management tool. |
− | Type `svnman help <subcommand>` for help on a specific subcommand. | + | Type `svnman help <subcommand>` for help on a specific subcommand. |
− | Type `svnadmin --version` to see the program version. | + | Type `svnadmin --version` to see the program version. |
Available subcommands: | Available subcommands: |
Revision as of 23:54, 24 February 2020
Svnman (pronounced ess-vee-en-man) 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.
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:
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
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. For details see the command-line interface.
Technical specification
The technical specification describes how the project works.
The software is written in PHP (tested on version 7.2) and shells out to the 'svn' command-line utility (tested on version 1.9.7).
Configuration data is kept in JSON format in $HOME/.config/svnman/config.json. Use the alias subcommand to specify configuration data via the command-line.
Command-line interface
general usage: svnman SUBCOMMAND [ARG...] [DIR...] A Subversion project management tool. Type `svnman help <subcommand>` for help on a specific subcommand. Type `svnadmin --version` to see the program version.
Available subcommands:
- config
- create
- maint
- freeze
- unfreeze (or thaw)
- release
- bump-minor
- bump-major
- browse
- gen-doc
- fix-version
Argument formats
ARG
An argument is a name prefixed with two dashes, optionally followed by whitespace and a value, depending on the argument. For example:
--no-trunk
Or:
--repo pcrepo
The special arguemnt '--' indicates that all subsequent command-line values are to be treaded as DIRs not as ARGs.
DIR
A path to a directory in the local file system. Absolute and relative paths are supported for input, but if paths are stored (such as with working base directories in repository aliases) the absolute paths are computed first.
PATH
A location in the local file system.
URL
A Uniform Resource Locator, typically with a scheme such as:
- http:
- https:
- file:
- svn:
NAME
Name format:
/^[a-z][a-z0-9_-]{0,42}$/
CODE
Code format:
/^[a-z][a-z0-9-]{0,16}$/
CONST
Const format:
/^[A-Z][A-Z0-9_]{0,16}$/
Subcommands
config
config: usage: svnman config [ARG...]
Configure an svnman repository alias. A repository alias associates a repo name with a repo location, allowing the repo name to be used as a shortcut for the repo location in commands which accept a --repo argument. A default working base folder and a ViewVC URL can also be associated with a repo name.
Note that the config file is in JSON format in:
$HOME/.config/svnman/config.json
Required arguments:
--repo-name NAME : the repository name --location URL : the repository location
Optional arguments:
--working-base PATH : location of working copy base (absolute path is resolved prior to storage) --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 NAME|URL : repository to create project in
Optional arguments:
--project-code CODE : project code (lowercase) --project-const 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|thaw [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 via `repo config`.
gen-doc
gen-doc: usage: svnman gen-doc
Generates svnman documentation for use in the project wiki:
https://www.progclub.org/wiki/Svnman
fix-version
fix-version: usage: svnman fix-version
If the PATCH version number is left on an even value (perhaps due to a failure during 'release') then this subcommand will bump it to the next odd value, making it a valid development PATCH version number again. If the PATCH version number is already an odd value this subcommand does nothing and fails indicating error.
For more info on our version numbers see:
https://www.progclub.org/wiki/Versioning
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.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: 11: generate tasks.wiki with TODO and Done sections...
- TODO: inc/lib.php: 2264: this needs better reporting. Some colour coding would be nice too.
- TODO: inc/lib.php: 2267: need to support other version file formats. Especially *.sh and *.ini formats.
- TODO: inc/lib.php: 2270: add a --debug command-line option.
- TODO: inc/lib.php: 2272: add a 'latest' subcommand that reports if the current branch is the latest and if not what is.
- TODO: inc/lib.php: 2279: add support for 'browse' subcommand.
- TODO: inc/lib.php: 2281: add support for 'fix-version' subcommand. Will increment even patch version to odd number.
- TODO: inc/lib.php: 2284: clean up after ourselves, delete temp files and directories...
- TODO: inc/lib.php: 2287: add support for --tarball generation during release.
- TODO: inc/lib.php: 2289: improve the documentation.
- TODO: inc/lib.php: 2294: add a --json argument which causes program output to be in stable JSON format for better integration.
LOW
- THINK: inc/lib.php: 1590: do we want to just automatically mkdir -p the working base..?
- THINK: inc/lib.php: 2275: do we want an optional argument --version-file for manually nominating the version file..? (At the moment we prefer convention over configuration.)
- THINK: inc/lib.php: 2297: consider adding an interactive mode that will confirm options or ask questions.
Done
Stuff that's done. Latest stuff on top.