========= BundleMan ========= :author: Benoit Delbosc :address: bdelbosc _at_ nuxeo.com :version: BundleMan/1.2.0 :revision: $Id$ :Copyright: (C) Copyright 2006 Nuxeo SAS (http://nuxeo.com). This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. :abstract: This document describes the usage of the BundleMan_ tool. This tool enables to release application with versioned products using subversion. .. sectnum:: :depth: 1 .. contents:: Table of Contents Introducing BundleMan ===================== What is BundleMan ? ------------------- BundleMan manages the release of applications built on versioned products under subversion_ (aka versioned multi modules). An application is seen as a products suite defined using subversion_ `svn:externals`_ property. An application is a bundle of products. Products are versioned pieces of software. Releasing an application is about taking care of tagging the source repository, managing version of each products, managing CHANGELOG, creating a source package archive, giving ways to maitain a release without blocking the trunk development. Main features: * BundleMan is free software distributed under the `GNU GPL`_. * It uses a recommended `trunk/branches/tags`_ repository layouts for products and bundles. * It uses standard versioning MAJOR.MINOR.BUGFIX-RELEASE for products. * Versioning of products is done automaticly by analysing a CHANGES file. * Enforce CHANGELOG quality by requiring a product CHANGES file. * It Generates an application CHANGELOG. * There is no locking of the trunk or version's conflict when patching a released application. * Can manage public, private or remote products. * BundleMan is written in python and can be easily customized. Where to find BundleMan ? ------------------------- Get the latest package from python `Cheese Shop`_. Or use the bleeding edge :: svn co http://svn.nuxeo.org/pub/tools/bundleman/trunk bundleman Installation ------------ See the INSTALL_ file for requirement and installation. Examples -------- You can play with BundleMan in a sandbox using the unit test environment. From the extracted archive:: $ python setup.py test running test ... INFO: Archive: /tmp/bm-jE9JMJ/co/APP.tgz ... Ran 6 tests in 72.976s OK Look at the temporary folder ``/tmp/bm-{WhAtEvEr}/`` you will find a ``svn`` folder which contains the svn sandbox repository and a ``co`` folder with working copies of an application. For example ``co/app`` is a trunk bundle with 2 empty products ``foo`` and ``bar``. You can test some `bm-bundle` commands from here, try ``bm-bundle -v`` then try to release this apps following the use case below. Documentation ------------- This page is the main BundleMan_ documentation, there are also: * CHANGES_ for information about distribution contents. * INSTALL_ for requirement and installation. * API_ documentation generated with epydoc_. Use cases ========= Inititialize an application to use BundleMan -------------------------------------------- * Create svn `trunk/branches/tags`_ repository layouts for bundles and products:: somewhere/bundles AppA trunk dev bundle with svn:externals that point to products branches branches created to patch a released application tags released application ... somewhere-else/products ProdA trunk branches tags ProdB trunk branches tags ... * See `svn:externals`_ to setup/configure your bundle. * BundleMan intialize - Checkout your bundle:: svn co somewhere/bundles/AppA/trunk AppA - Initialize all products that you want to manage with BundleMan, products must be in a trunk or branch. Go into the product directory and run a:: bm-product --init This will add a CHANGES, VERSION and HISTORY files to the product and add a svn property named bundleman. - Initialize the bundle from the bundle working copy by running:: bm-bundle --init It will create a `svn-externals` file that contains the svn externals definition. Working on an application ------------------------- * Changing bundle definition. You should edit the `svn-externals` file to update your bundle definition, then :: svn ps svn:externals -F svn-externals . svn commit -m"udpate the bundle definition" -N svn-externals . The `svn-externals` file is usefull to have readable `svn:externals` diff and to look at the bundle contents from a trac. Be sure that all developpers use this file to edit the bundle definition. * Working on a product. When working on a product sources, in addition to your commit message, you will have to fill a CHANGES file. The content of this file is the changes between the current dev and the last product release. This file contains 4 sections: - Requires: things that must be done to use or install this new release. - New features: list of new features, customer oriented. - Bug fixes: list of bug fix. - New internal features: list of new features, devel oriented. CHANGES exemple:: Requires ~~~~~~~~ - ProdC > 1.2.3 New features ~~~~~~~~~~~~ - Enable customer ... Bug fixes ~~~~~~~~~ - fix #1234: Site error when... New internal features ~~~~~~~~~~~~~~~~~~~~~ - API Changes ... Depending on the CHANGES content BundleMan will compute the new version of the product. When releasing, BundleMan will ask you to fill this file if it is empty while you have commited sources since the last product release. This file is reseted during product release and flush into an HISTORY file. The HISTORY file is turn into a CHANGELOG.txt file in the release archive. Product CHANGELOG.txt exemple:: =========================================================== Package: ProdA 3.2.0 =========================================================== First release built by: ben at: 2006-09-19T08:03:54 SVN Tag: path/to/products/ProdA/tags/3.2.0 Build from: path/to/products/ProdA/trunk@1234 Requires ~~~~~~~~ - ProdC > 1.2.3 New features ~~~~~~~~~~~~ - Enable customer ... Bug fixes ~~~~~~~~~ - fix #1234: Site error when ... New internal features ~~~~~~~~~~~~~~~~~~~~~ - API Changes ... =========================================================== Package: ProdA 3.1.0 =========================================================== First release built by: ben at: 2006-09-17T18:03:41 SVN Tag: path/to/products/ProdA/tags/3.1.0 Build from: path/to/products/ProdA/trunk@1123 Requires ~~~~~~~~ .... Releasing an application ------------------------ On a working copy of the trunk bundle * Check the status of your working copy:: $ bm-bundle INFO: List of actions to do: ProdA 3.2.0-1 Requires a svn update/commit. ProdB 1.0.0-1 New version: 1.1.0-1 ProdC 2.0.0-1 CHANGES file must be filled !. WARNING: Bundle not ready to be released. Running `bm-bundle` without option is purely introspective. * Depending on the status you may need to fill product's CHANGES file, commit locally modified or svn update products. Re run bm-bundle until the status is 'Ready':: $ bm-bundle INFO: List of actions to do: ProdB 1.0.0-1 New version: 1.1.0-1 ProdC 2.0.0-1 Nex version: 2.0.1-1 INFO: Ready: Going to release some products. * Release the application:: $ bm-bundle --release=APPA-2006-rc1 INFO: Analyze all products ... INFO: Tag product ProdB version 1.1.0-1 INFO: Tag path/to/products/ProdB/tags/1.1.0 done. .... INFO: Create a bundle tag APPA-2006-rc1 INFO: Analyze all products ... INFO: Creating bundle path/to/bundles/AppA/tags/APPA-2006-rc1 Note that in addition to the new bundle tags, it created releases for ProdB and ProdC products. * Create a CHANGELOG of the application since the previous release APPA-2005:: $ bm-bundle --changelog APPA-2005:APPA-2006-rc1 > CHANGELOG.txt You can edit, add and commit this file to the APPA-2006-rc1 tag. * Create a tarball archive:: $ bm-bundle --archive APPA-2006-rc1 -o /tmp/ INFO: Analyze all products ... INFO: Creating archive: APPA-2006-rc1.tgz INFO: Archive: /tmp/APPA-2006-rc1.tgz In this archive you will have a `version.txt` for the bundle (with 'APPA-2006-rc1' content) and for each products. Patching a release ------------------ You want to patch the APPA-2006-rc1 to release the rc2. From a working copy of he trunk bundle * Create a bundle branch:: $ bm-bundle --branch=APPA-2006-rc1 INFO: Branching path/to/bundles/app/tags/APPA-2006-rc1 -> path/to/bundles/app/branches/APPA-2006-rc1 hash_tag: rel1058079549. INFO: Creating bundle path/to/bundles/AppA/branches/APPA-2006-rc1 This will create a branch for each versioned products and create a new bundle in `bundles/AppA/branches`. Note that the product branch is created using a hash of the RELEASE_TAG because it hides the RELEASE_TAG in the case of a private bundle that uses public products. This means that you will not have 'MYSECRETPROJECTrc1' tag in a a product that is on a public svn. * Either switch to the branch:: svn switch path/to/bundles/app/branches/APPA-2006-rc1 or checkout the new bundle branch:: svn co path/to/bundles/app/branches/APPA-2006-rc1 * Commit the fixes and update CHANGES in the different products * Release: - Check the status:: $ bm-bundle INFO: List of actions to do: ProdA 3.2.1-1 New version: 3.2.2-rel1058079549-1 INFO: Ready: Going to release some products. - Depending on the status you may need to fill product's CHANGES file, commit locally modified or svn update products. - Release:: $ bm-bundle --release APPA-2006-rc2 INFO: Analyze all products ... INFO: Tag product ProdA version 3.2.2-rel1058079549-1 INFO: Tag path/to/products/foo/tags/3.2.2-rel1058079549 done. ProdB 1.1.0-1 Already released. ProdC 2.0.1-1 Already released. INFO: Create a bundle tag APPA-2006-rc2 INFO: Analyze all products ... INFO: Creating bundle path/to/bundles/AppA/tags/APPA-2006-rc2 Note that ProdA is released with the version 3.2.2-rel1058079549-1, the release tag may change for a same target release like (APPA-2006-beta, APPA-2006-rc1 ...rc2 and final), using a hash we will not have a weird APPA-2006-rc1 tag in the final APPA-2006 bundle. * You can keep this branch to patch APPA-2006-rc2 and create the final APPA-2006. * Merge your patch to the trunk: `bm-bundle --merge=APPA-2006-rc2` This will merge all products from bundle/App/tags/APPA-2006-rc2 to products in the bundle/AppA/trunk and switch to trunk. **NOT YET IMPLEMENTED** * Fix eventual conflict then commit. That's all. Product release --------------- You can release a single product using `bm-product --release` Mutliple release ---------------- You can release an AppB that shares products with AppA without any version conflit. Verifying a package installation -------------------------------- When creating an archive BundleMan adds a MD5SUMS file, so you can check that a tarball installation is valid:: cd path/to/app md5sum -c MD5SUMS && echo "Package verified successfully" *Note that md5sum will not complain about new files.* BundleMan commands ================== There is only 2 commands provided by BundleMan, bm-product to manage a product and bm-bundle to manage the bundle (ie the application). Default operation without options are purely introspective, zero risk. To check what BundleMan is doing you can use the debug option `--debug` or look into the log file `/tmp/bundleman.log`. bm-product ---------- Usage ~~~~~ :: bm-product [options] [WCPATH] bm-product is a product release manager. See BundleMan documentation for more information. WCPATH is a svn working copy of a product. Product follows the classic trunk/tags/branches svn tree. Product is versioned using 3 files: * CHANGES (not present in an archive) this file contains 4 sections: - Requires: things that must be done to install this new release. - New features: list of new features customer oriented. - Bug fixes: list of bug fix. - New internal features: list of new features devel oriented. This file *MUST* be filled during devel of the product. This file is reseted during product release. * VERSION: (or version.txt in an archive) this file contains the product name, product version and release number. The version format is MAJOR.MINOR.BUGFIX[-branch_name]. A new version is automaticly computed using the content of the CHANGES file with the following rules: - If there is *ONLY* bug fixes increment the BUGFIX number else increment the MINOR number. - If the svn url is a branch append the branch name to the version. * HISTORY (or CHANGELOG.txt in an archive) This file contains the concatenation of all CHANGES. Exemples ~~~~~~~~ :: bm-product Display status and action to be done for WCPATH. bm-product --init Initialize the WCPATH product: * Check that the WCPATH point to a trunk svn url. * Check that tags and branches svn url exists. * If missing prompt the user to add VERSION, CHANGES and HISTORY files to the product working copy and commit them. bm-product --release Release the WCPATH product: * Analyse the working copy: - Checks that WCPATH is up to date with the svn. - Parses the CHANGES file and computes the new version - If CHANGES is empty checks the that there is no diff between the WCPATH and the tagged version. * Create a tag using WCPATH svn revision: tags/VERSION * Fush CHANGES into HISTORY, update VERSION files and commit, in the tag and the WCPATH url. bm-product --archive -o /tmp Create a tarball archive in the /tmp directory. The product must be released. The tarball contains a MD5SUMS file and can be verified using `md5sum -c MD5SUMS`. Options ~~~~~~~ :: --version show program's version number and exit --help, -h show this help message and exit --status, -s Show status and action to be done for WCPATH. --init Initialize the WCPATH product. --release Release the product WCPATH. --major Increment the MAJOR number instead of the MINOR number of the version. --again Rebuild the same version, increment the release number. --archive, -a Build a targz archive. --output-directory=OUTPUT_DIR, -o OUTPUT_DIR Directory to store the archive. --force, -f No prompt during --init. Replaces an existing tag during --release. Release even with locally modified files. --verbose, -v Verbose output --debug, -d Debug output bm-bundle --------- Usage ~~~~~ :: bm-bundle [options] [WCPATH] bm-bundle is a bundle release manager. See BundleMan documentation for more information. WCPATH is a svn working copy path of a bundle, using current path if not specified. A bundle is an suite of products, this suites is defined using svn:externals property of the bundle folder. A bundle follows the classic trunk/tags/branches svn tree. Products may be versionned using bm-product tool. Examples ~~~~~~~~ :: bm-bundle Display status and action to be done. bm-bundle --init Initialize WCPATH bundle by adding svn-externals file to trunk bm-bundle --release APPrc1 Create release bundle in tags/APPrc1 that point to released products. bm-bundle --release APPrc1 -a Create a release and a targz archive in one step. bm-bundle --archive APPrc1 -o /tmp Create a targz archive in /tmp directory. The tarball contains a MD5SUMS file and can be verified using `md5sum -c MD5SUMS`. bm-bundle --archive APPrc1 --archive-root-directory Products Create a targz archive of APPrc1 release with a root folder named Products. bm-bundle --branch APPrc1 Create a branch bundle in branch/APPrc1 that point to branched products. A product branch will be created for each versioned products. The branch name use a hash(APPrc1) key. bm-bundle --changelog APPrc1:APPrc2 Output a global bundle changelog between bundle tags. bm-bundle --release APPrc2 --changelog APPrc1: -a -o /tmp --scp bar:/tmp Create a release with a global changelog, build the targz archive, scp it to bar:/tmp in one step. Options ~~~~~~~ :: --version show program's version number and exit --help, -h show this help message and exit --status, -s Show action to be done. --init, -i Initialize the bundle working copy. --release=RELEASE_TAG Release the bundle. -a Build a tar gz archive, must be used with --release option. --archive=RELEASE_TAG Build a tar gz archive from an existing RELEASE_TAG. --archive-root-directory=ARCHIVE_ROOT The name of the root directory in the archive, default is RELEASE_TAG. --output-directory=OUTPUT_DIR, -o OUTPUT_DIR Directory to store the archive. --scp=REMOTE_PATH scp the archive to a REMOTE_PATH. --branch=RELEASE_TAG Branch the bundle release. --changelog=TAG1:TAG2 Output a changelog between 2 bundle tags. If TAG2 is missing it uses the RELEASE_TAG. --changelog-url=TAG1_URL:TAG2_URL Output a changelog between 2 bundle url tags. --force, -f No prompt during --init. --log-file=LOG_FILE, -l LOG_FILE The log file path. Default is ~/bundleman.log. --verbose, -v Verbose output --debug, -d Debug output .. _INSTALL: INSTALL.html .. _CHANGES: CHANGES.html .. _API: api/index.html .. _BundleMan: http://public.dev.nuxeo.com/~ben/bundleman/ .. _epydoc: http://epydoc.sourceforge.net/ .. _`Cheese Shop`: http://www.python.org/pypi/bundleman/ .. _`svn:externals`: http://svnbook.red-bean.com/en/1.2/svn.advanced.externals.html .. _subversion: http://subversion.tigris.org/ .. _`trunk/branches/tags`: http://svnbook.red-bean.com/en/1.2/svn.branchmerge.maint.html#svn.branchmerge.maint.layout .. _`GNU GPL`: http://www.gnu.org/licenses/licenses.html .. Local Variables: .. mode: rst .. End: .. vim: set filetype=rst: