Documentation¶
ZTM: a free software, Topic Maps driven CMS (Content Management System), but also a CMS to maintain and author topic maps.
Documentation¶
This documentation is for 2009.1, for other versions see the page linking to documentation for all versions.
Packages¶
The following four packages represent the core of a ZTM Topic Maps installation and are part of the first quarterly release (November 2009).
- ztm.topicmaps
- The core Topic Maps engine.
- ztm.interfacemanager
- Module mapping ZCA marker interfaces to topics based on their topic map properties.
- ztm.navigator
- Simple Omnigator-like interface to inspect a topic map.
Further packages can be found in the repository
Downloads¶
The preferred and easiest way to get ZTM is to use zopeproject to set up a zc.buildout infrastructure. The resulting project can be used to include ztm.publisher and ztm.demonstration. See the installation descriptions on the front page.
You can find (hopefully) comprehensive installation instructions
Get the code¶
ztmproject.org keeps the project’s source code in Bazaar repositories available at ztmproject.org/code/
You can check them out like this by replacing ztm.packagename with the package that you want:
$ bzr get http://ztmproject.org/code/ztm.packagename
Alternatively you can use the launchpad mirrors:
$ bzr get lp:ztm.packagename
These repositories are read-only. You contribute your changes by publishing a branch with your changes somewhere and sending a merge request.
Package naming policy¶
ZTM builds on many packages from the FOSS (Free and Open Source Software) community.
All packages should be in the ztm module/namespace like this: ztm.topicmaps and ztm.navigator etc.
Python Package Index policy¶
There are quite a few packages in ZTM. To avoid spamming the Python Package Index (PyPI) feed every time we release an update only a select few packages, like the meta-package ztm.publish, are uploaded there.
The remaining eggs are placed in http://ztmproject.org/snapshots/ and retrieved by the buildout -based installation process.
Repository policy¶
For now all packages are simply kept in their own branch. In the near future we will start using packed repositories (a bazaar feature) to keep multiple versions of a branch available.
Versioning policy¶
ZTM follows a traditional major.minor.patch versioning policy.
- Major versions break API and move or remove functionality.
- Minor versions typically introduce new functionality but may remove deprecated functionality.
- Patch versions are only bugfixes or improved translations/documentation.
Released versions must be tagged in the repository. version.txt should always contain the version number.
All notable changes should be added to CHANGES.txt.
Release policy¶
Each package is versioned independently to allow its development to proceed at its own pace. Dependencies on particular versions are marked in setup.py according to rules defined by distutils/setuptools.
We aim for quarterly releases. To achieve this we must heavily rely on unit-tests to keep the packages stable. Please always submit unit-tests for bug-fixes or new features.
Packages that we consider reasonably stable are included in the toolkit. Currently the following packages are included:
- ztm.topicmaps
- ztm.interfacemanager
- ztm.navigator
Fixed bugs should be backported when feasible and new patch releases will be made for that particular package.
If no changes has been made to a package the previous version will be included in the quarterly release.
Develop eggs¶
Develop eggs and release candidates are marked by appending dev or RC to the target version number.
These eggs should never be uploaded to PyPI.
API Compatibility¶
We only promise API compatibility from version 1.0 and inside major versions for non-deprecated features.
Deprecation¶
Features must be marked with deprecation for at least 1 year (4 releases) before they can be removed.
Only discouraged or obsolete features should be deprecated.
Documentation policy¶
Documentation for the different releases remain available under ztmproject.org/documentation.
Licensing¶
All modules are licensed under GNU General Public License version 3 (GPL3). In addition all non-GUI packages are also licensed under GNU Lesser General Public License (LGPL3)
ZTM packages occasionally include modules and packages from other projects that have their own licenses. Each file should have their own copyright preamble and be noted in the package documentation..
Dependencies¶
The 2009.1 release depend on Zope 3.4, particularly the known good set of packages for 3.4.
We expect to transition to the Zope Toolkit 3.5 once it is stabilized and released. The main difference is that ZMI is split out and that dependencies on zope.app.* should disappear.
Packages should say in their README.txt if they are reusable outside of ZTM eg.:
This package is intended to be independently reusable in any Python project. It is maintained by ztmproject.org.
This package is intended to be independently reusable in any Zope project. It is maintained by ztmproject.org.
This package is at present not reusable without depending on a large chunk of ZTM Topic Maps and its assupmtions. It is maintained by ztmproject.org.
Most packages will not be reusable outside ZTM.