This is the root of the Crushinator project, a special one-stop repository that combines the development (and installation) of several independant (but related) python packages:

• crushinator.framework, the core classes defining the API that all Crushinator-based projects implment.
• crushinator.toolkit, a set of common implementations of various components covering many different use-cases.
• Crushinator, a set of reference implementations showing the different types of front-end user interfaces. Considered production-quality code, and safe to use in lieu of (or in tandem with) another preferred front-end user interface. Installs a central crushinator script if installed directly.
• crushinator.integrationtests, a special egg containing integration tests. Not released.

Consider this repository a suite of packages. Each should be autonomous (save for a dependancy on crushinator.framework), and can be developed and tested separately. They're brought together here, not just to keep the author's administration headache to a minimum, keeping issues, documentation, and other artifacts in a central place, but also to allow a logical location for broader integration tests.

This README lives within a zc.buildout structure, used for testing and to provide a consistent, almost instant development environment.

The src directory contains the source code for crushinator.framework, and the other packages described above. Each subdirectory within is a complete python egg file structure.

The docs folder contains design, implementation, and userland documentation. It (like this file) is written in reStructuredText, and is written for documentation to be generated with Sphinx.

Each egg structure in src mirrors this one in terms of documentation. There is a README.rst file explaining what the package does and quick start/installation instructions.

Each egg also contains a docs directory, containing more detailed documentation, API references, userland docs, etc.

Unit and functional tests are located in the tests directory within the module structure (e.g. crushinator.framework.tests).

See Developing Crushinator for further details and instructions on using the included buildout.cfg (the recommended method), or a virtualenv environment.

See Testing Crushinator for more information about writing and running tests.

See Documenting Crushinator for documentation guidelines and instructions on generating the user manual.

The Crushinator packages are versioned incrementally, using a 3 part numeric notation (e.g., 1.2.3). There is no anticpated limit for any of the component numbers (so 100202202.212121243123412.242345345423563456 is theoretically possible, but not likely).

All numbers start at 0.

• The first number (5.1.43) indicates 'feature' or 'major' releases. This includes additional package-level functionality, API changes, etc. The 0.x.x versions are considered pre-release versions.
• The second number (5.1.43) is used for smaller, but still significant, releases within a feature release. This number is reset to 0 when the feature release number is incremented (so the next major release would be (6.0.0). API changes are not allowed within a 'first dot' release. New features can be added, but when they are incorporated is up to the release manager.
• The third number (5.1.43) is strictly for defects (bugs, security flaws, documentation updates). New features are not allowed, nor are API changes. These versions can be released at will, and should be entirely safe for all users of the particular X.X.Y release to upgrade to. This number resets to zero when the 'first dot' number is incremented or rolled over.

Alphas, Betas, Release Candidates, and other specialized releases will be indicated with a dash (-) and a few characters to indicate the purpose. Some examples:

• 0.1.0-alpha: an 'alpha', or very early release of the 0.1.0 version. As bugs are fixed within that alpha, the third number increments as in 'typical' releases.
• 5.2.0-RC1: a 'release candidate' of the 5.2.0 version. A second release candate would be 5.2.0-RC2.

With the exception of a very few situations, special releases will always be on 'full' releases, e.g., a version with no bugs (e.g. X.X.0)

A quick counting example: