"The good news about computers is that they do what you tell them to do. The bad news is that they do what you tell them to do."
-- unsure; often attributed without source to information philosopher Ted Nelson
Each software package should have a standard version numbering system, documented in the README file in the package's top-level directory. The version numbering system might also be documented elsewhere, like the User's Guide. An example:
Version Numbering ================= Version numbers consist of major, minor and micro versions (such as "1.0.0"), optionally followed by a beta version (such as "1.0.0b1"). A major version of "0" indicates an alpha release (ex. "0.1.0"). This should be considered unstable, potentially buggy, and with frequent changes to functionality and implementation, including changes to the data formats, APIs, and protocols, which could render previous data or programs incompatible. An extension of "b" followed by a number indicates a beta release before the stable release of the same version. Beta versions implement new features that have not been thoroughly tested, and should be considered unstable and potentially buggy. A major version of "1" or above indicates a stable set of data formats, APIs, and protocols, allowing data and programs from earlier versions to be upwards compatible with later versions. A change in the major version number indicates that older data sets and programs may not work with the new version; the new version should include instructions for converting to the new format. A change in the minor version number indicates the addition of significant new features. A change in the micro version number indicates bug fixes and other small changes.
The version number of the software package should be documented at the top of the package's README file and on the title pages of its User's and Developer's Guides.
Every program should accept the command line argument "--version" (optionally having short form "-V"). When invoked with "--version", the program should ignore the rest of the arguments, print a message to stdout, then exit successfully without performing its normal function. The message should include the program name, package name if the program is a subsidiary part of the package, version number, origin, and copying protections. For example:
% hello --version Hello 1.0.0 Copyright (C) 2001 Ken Gaillot Jr. This software comes with NO WARRANTY, to the extent permitted by law. For copying restrictions, read the file named COPYING included with the distribution, or the "License" section of this software's User's Guide.
Each software package should have a plain text file named "ChangeLog" in its top-level directory. (If the package is very big, a ChangeLog file for each subdirectory might be better.) All changes to the package should be logged in this file, with newer items added to the top. Some version control tools can generate this file automatically.
Each entry should have the date, the author's name, the name of the file changed, and a brief comment about what changed. Some example ChangeLog entries:
2001-03-26 Ken Gaillot Jr. <nobody@nowhere.com> * example.c (example_function): New argument wooga. All callers changed. * otherfile.h: New structure 'potato'. 2001-03-23 Ken Gaillot Jr. <nobody@nowhere.com> * First release of package.
When new bugs are detected, the ChangeLog can help find recent changes that may have triggered the bug.
Every package should also have a plain text file named "NEWS" in its top-level directory containing a list of user-visible changes worth mentioning. Newer items should be at the top of the file. The NEWS file lets users who are upgrading from an older version of the package know what to expect.
Some automated tools help maintain different versions a software package, with the ability for multiple developers to work on the code without conflicting with each other's changes, keep old versions available, and so forth. The two most popular are rcs and cvs. I personally haven't used them, so you're on your own.
Any security fix warrants a new version release (even if it's just a micro version number). Bug fixes usually warrant a new version release, since bugs can sometimes be exploited as security holes.