Documentation update.

More to come...

README.mkd

@@ -13,10 +13,14 @@ Tito offers the following features:
  - Build source and binary "test" rpms off most recently committed code.
  - Build multiple source rpms with appropriate disttag's for submission to the
    Koji build system
+ - Build rpms via the "mock" tool.
  - On a per-branch basis in git:
    - Maintain concurrent version streams.
    - Vary the way packages are built/tagged.
  - Report on any diffs or commits messages missing since last tag.
+ - Define release targets to publish your packages to yum repositories, or
+   the Fedora build system.
+ - Define custom builder/releaser implementations for your own project needs.
  - Build packages off an "upstream" git repository, where modifications in the
    "downstream" git repository will be applied as a patch in the source rpm.
  - Manage all of the above for a git repository with many disjoint packages
@@ -96,6 +100,7 @@ Once a package is tagged you will need to push both the auto-commit and the tag
 to your remote git repository before tito will let you build it. (better
 support for standalone git repositories is coming, for now --offline will help)
 
+See "man tito" for more options.
 
 BUILDING PACKAGES
 =================
@@ -120,6 +125,55 @@ recently committed work. (NOTE: does *not* include uncommitted changes)
 TODO: Document the use of --release, which is complicated and untested against
 Fedora's Koji.
 
+See "man tito" for more options.
+
+
+RELEASING PACKAGES
+==================
+
+Tito supports a mechanism where you can define multiple release targets.
+
+In rel-eng/releasers.conf, create a section like:
+
+[yum-f15-x86_64]
+releaser = tito.release.YumRepoReleaser
+builder = tito.builder.MockBuilder
+builder.mock = fedora-15-x86_64
+rsync = fedorapeople.org:/srv/repos/dgoodwin/tito/fedora-15/x86_64/
+
+You can define as many release targets as you like with various configurations.
+To publish the most recently tagged build in your current branch you would run:
+
+    tito release yum-f15-x86_64
+
+You can specify multiple targets on the CLI.
+
+See "man 8 releasers.conf" for more information on defining release targets.
+
+See "man tito" for more information on CLI arguments to "tito release".
+
+
+
+CUSTOM BUILDERS / TAGGERS / RELEASERS
+=====================================
+
+If the existing implementations Tito provides are not sufficient for
+your needs, it is possible to define a lib_dir in tito.props globalconfig
+section. This is a directory that tito will add to the python path during
+execution, allowing you a place to define your own custom implementations of
+builders, taggers, and releasers.
+
+The process of actually writing a custom Builder/Tagger/Releaser is an exercise
+left to the reader, but essentially you will want to work off the code in the
+tito.builder module. Inherit from the base Builder, and override the methods
+you need to.
+
+Please note that if you store your custom implementations inside your source
+tree, they will need to be kept in sync in all branches you are using for
+consistent behavior. Also, there are no guarantees that tito will not change in
+future releases, meaning that your custom implementations may occasionally need
+to be updated.
+
 
 TROUBLESHOOTING
 ===============
@@ -140,61 +194,13 @@ invocation.
 CONFIGURATION
 =============
 
-Some user specific settings can be defined in ~/.titorc:
+See:
 
-# Default Location to write temp files, tarballs and rpms to:
-RPMBUILD_BASEDIR = /tmp/tito
-
-# Specify packages to not auto-install. Uses a simple string contains
-# comparison.
-NO_AUTO_INSTALL = project-subpkg1 project-subpkg2
-
-The main tito configuration file resides in your git repository at /rel-eng/tito.props. Below is an attempt to document each supported section and option:
-
-## Section: [globalconfig]
-
-### default_builder / default_tagger
-
-Specified the default builder to use if the package does not specify it's own in a package specific tito.props. 
-
-I.e:
-
-> default_builder = spacewalk.releng.builder.Builder
-> default_tagger = spacewalk.releng.tagger.VersionTagger
-
-### lib_dir
-
-Specifies an optional directory where you may be storing custom tito builders/taggers in your git repository. If you have very specific build needs, this can be useful to tailer the core tito classes with inheritance, or to write your own from scratch. Note that this has disadvantages as well, as this code will need to be kept in all your branches, and can have implications when building tags from the past.
-
-> lib_dir=rel-eng/lib/
-
-### tag_suffix 
-
-An optional specification of a suffix to append to all tags created by tito for this repo. Can be useful for situations where one git repository is inheriting from another, but tags are created in both. The suffix will be an indicator as to which repo the tag originated in.
- 
-> tag_suffix = -mysuffix 
-
-## Section: [cvs]
-
-Tito has support for releasing builds in a CVS driven buildsystem, similar to the former Fedora build infrastructure. (WARNING: this has now been replaced with a git infrastructure, this module no longer can be used with Fedora)
-
-
-> [cvs]
-> cvsroot = :ext:myuser@cvs.fedoraproject.org:/cvs/extra
-> branches = CVSBRANCH1 CVSBRANCH2
-
-## Section [gitrelease]
-
-Tito has support for releasing builds in Fedora's git build system. Your spec file and patches will be synched into the first branch listed below, then merged into the following branches.
-
-> branches = master f14/master f13/master
-
-
-
-[requirements]
-tito=0.2.0
+    man 5 tito.props
 
+    man 5 releasers.conf
 
+    man 5 titorc
 
 
 

releasers.conf.5.asciidoc

@@ -0,0 +1,76 @@
+releasers.conf(5)
+=================
+include::man.asciidoc[]
+
+NAME
+----
+releasers.conf - Config file defining release targets where builds can be published.
+
+
+SYNOPSIS
+--------
+None
+
+
+DESCRIPTION
+-----------
+Tito allows projects to define their own release targets, which can specify the exact releaser implementation to use (potentially a custom one), and any arguments it may need for a specific type of build.
+
+
+RELEASERS
+---------
+
+Tito includes several releaser implementations that can be used in releasers.conf. Additionally you may define a lib_dir in your tito.props globalconfig section, and place your own custom implementation of a releaser there.
+
+tito.release.YumRepoReleaser::
+Releaser which will build your packages, rsync down an existing yum repository, place your packages in it, regenerate the yum repodata, and rsync the yum repository back up.
+
+tito.release.FedoraGitReleaser::
+
+Releaser which will checkout your project in Fedora git using fedpkg. Sources are then synced to the first branch your releaser lists. After this tito will git merge the first branch into all other listed branches, triggering builds in each.
+
+WARNING: Highly experimental, very prone to failure if merging master into your branches is likely to cause a conflict. You will need to cleanup manually if this occurs.
+
+ [fedora-git]
+ releaser = tito.release.FedoraGitReleaser
+ branches = master el5 el6 f14 f15 f16
+
+tito.release.CvsReleaser::
+Releaser which will submit builds through CVS build systems. (no longer useful for Fedora) The CVS module is checked out, sources, spec file, and patches are synced and committed, the release is tagged (make tag), and then submitted to the build system. (make build)
+
+ [cvs]
+ releaser = tito.release.CvsReleaser
+ cvsroot = :ext:myuser@cvs.fedoraproject.org:/cvs/extra
+ branches = BRANCH1 BRANCH2
+
+tito.release.KojiReleaser::
+Highly experimental, ignore for now.
+
+
+
+EXAMPLE
+-------
+
+ [yum-f15-x86_64]
+ releaser = tito.release.YumRepoReleaser
+ builder = tito.builder.MockBuilder
+ builder.mock = fedora-15-x86_64
+ rsync = fedorapeople.org:/srv/repos/dgoodwin/tito/fedora-15/x86_64/
+
+ [yum-f16-x86_64]
+ releaser = tito.release.YumRepoReleaser
+ builder = tito.builder.MockBuilder
+ builder.mock = fedora-16-x86_64
+ rsync = fedorapeople.org:/srv/repos/dgoodwin/tito/fedora-16/x86_64/
+
+ [yum-el6-x86_64]
+ releaser = tito.release.YumRepoReleaser
+ builder = tito.builder.MockBuilder
+ builder.mock = epel-6-x86_64
+ rsync = fedorapeople.org:/srv/repos/dgoodwin/tito/epel-6/x86_64/
+
+ [cvs]
+ cvsroot = :gserver:cvs.example.com:/cvs/dist
+ branches = FEDORA-15
+
+

src/tito/cli.py

@@ -428,9 +428,6 @@ class ReleaseModule(BaseCliModule):
     def __init__(self):
         BaseCliModule.__init__(self, "usage: %prog release [options] TARGET")
 
-        self.parser.add_option("--dist", dest="dist", metavar="DISTTAG",
-                help="Dist tag to apply to srpm and/or rpm. (i.e. .el5)")
-
         self.parser.add_option("--no-cleanup", dest="no_cleanup",
                 action="store_true",
                 help="do not clean up temporary build directories/files")
@@ -440,8 +437,7 @@ class ReleaseModule(BaseCliModule):
 
         self.parser.add_option("--dry-run", dest="dry_run",
                 action="store_true", default=False,
-                help="Do not actually commit/push anything during --release.",
-                )
+                help="Do not actually commit/push anything during release.")
 
         self.parser.add_option("--all-starting-with", dest="all_starting_with",
                 help="Run all release targets starting with the given string.")

tito.8.asciidoc

@@ -135,29 +135,11 @@ WARNING: uses `sudo rpm -Uvh --force`
 Apply 'DISTTAG' to srpm and/or rpm. (e.g., ".el5")
 
 --test::
-use current branch HEAD instead of latest package tag
+use current branch HEAD instead of latest package tag.
 
 --no-cleanup::
 do not clean up temporary build directories/files
 
---tag='PKGTAG'::
-build a specific tag instead of the latest version
-(e.g., `spacewalk-java-0.4.0-1`)
-
---release::
-Release package according to repo configuration.
-(import into CVS and submit to build system, or create
-src.rpm's and submit directly to Koji)
-
-CAUTION: The `--release` option is complicated and untested against
-Fedora's Koji.
-
---cvs-release::
-Release package only in CVS. (if possible)
-
---koji-release::
-Release package only in Koji. (if possible)
-
 --list-tags::
 List tags for which we build this package. If you set --debug together
 with this option, you will see all tags and whether they are whitelisted
@@ -174,8 +156,45 @@ file is committed to CVS.
 --rpmbuild-options='OPTIONS'::
 Pass 'OPTIONS' to rpmbuild.
 
---scratch::
-Do scratch build (only for --koji-release)
+--builder='BUILDER'::
+Override the normal builder by specifying a full class
+path or one of the pre-configured shortcuts. Only useful if you need to override the default builder for some purpose, such as testing a build via mock.
+
+--builder-arg='BUILDER_ARGS'::
+Custom arguments specific to a particular builder. (key=value)
+
+
+
+`tito release [options] TARGETS`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Runs the release targets defined in rel-eng/releasers.conf.
+
+-h, --help::
+show this help message and exit
+
+--debug::
+print debug messages
+
+--offline::
+do not attempt any remote communication (avoid using
+this please)
+
+-o 'OUTPUTDIR', --output='OUTPUTDIR'::
+Write temp files, tarballs and RPMs to 'OUTPUTDIR'.
+(default /tmp/tito)
+
+--tag='PKGTAG'::
+build a specific tag instead of the latest version
+(e.g., `spacewalk-java-0.4.0-1`)
+
+--dry-run::
+Do not actually commit/push anything during release.
+
+--all-starting-with=ALL_STARTING_WITH::
+Run all release targets starting with the given string. (i.e.
+if you have defined release targets yum-f15 and yum-f14 in releasers.conf,
+--all-starting-with=yum will run only these targets, and ignore any others.)
 
 
 `tito report`
@@ -186,11 +205,21 @@ HEAD and their most recent tag, as well as a patch for
 that diff. Used to determine which packages are in need
 of a rebuild.
 
+EXAMPLES
+--------
+
+Build and install a test package from the latest code in current git HEAD::
+tito build --rpm --test -i
+
+Overriding the default builder to build via mock instead::
+tito build --builder mock --builder-arg mock=fedora-15-x86_64 --rpm
 
 
 SEE ALSO
 --------
 titorc(5)
+releasers.conf(5)
+tito.props(5)
 
 /usr/share/doc/tito-*/README.mkd
 

tito.props.5.asciidoc

@@ -22,16 +22,13 @@ Project settings can be stored in files:
 
 `GITROOT/SOME/PACKAGE/build.py.props`
 
-First tito.props is read, and if build.py.props in package directory is present, then it
-is read as well and options in build.py.props override those from tito.props.
+The global rel-eng/tito.props is generally where settings are defined. For some multi-project git repositories, individual packages can override these settings by placing a tito.props in the project directory. (i.e. same location as it's .spec file)
 
 
 SECTIONS
 --------
-There is several sections:
- * globalconfig
- * koji
- * cvs
+tito.props can contain several sections:
+
 
 GLOBALCONFIG
 ------------
@@ -39,28 +36,21 @@ This section is mandatory. At least in tito.props as you need to specify
 default builder and tagger for you project. You can use following variables:
 
 default_builder::
-You specify name of class which is used for building (creating rpm or src.rpm).
-You can either specify builders shipped with Tito (see BUILDERS section below)
-or use your own modules stored in GITROOT/rel-eng/lib/ path.
-I.e if you specify name spacewalk.releng.tagger.VersionTagger, then tito will
-check if exist file GITROOT/rel-eng/lib/spacewalk/releng/tagger.py and in it
-class VersionTagger. If this import will fail, then it will check if file
-/usr/lib/pythonX.Y/site-packages/spacewalk/releng/tagger.py with class
-VersionTagger exists.
+The fully qualified Builder class implementation to use.
+You can either specify builders shipped with Tito (see BUILDERS section below), or a custom builder located within the directory your `lib_dir` option points to.
 
 default_tagger::
-You specify name of class which is used for tagging (bump up version/release
-and create changelog). You can either specify taggers shipped with Tito (see
-TAGGERS section below).
-Search path of class is exactly the same as in default_builder.
+The fully qualified Tagger class implementation to use.
+You can either specify builders shipped with Tito (see TAGGERS section below), or a custom builder located within the directory your `lib_dir` option points to.
+
+lib_dir::
+Optional property defining a directory to be added to the Python path when executing tito. Allows you to store custom implementations of Builder, Tagger, and Releaser.
 
 builder::
-This option is used in build.py.props and define builder class for one specific
-package.
+This option is used in project specific tito.props only, and allows that project to override the default_builder defined in rel-eng/tito.props.
 
 tagger::
-This option is used in build.py.props and define tagging class for one specific
-package.
+This option is used in project specific tito.props only, and allows that project to override the default_tagger defined in rel-eng/tito.props.
 
 changelog_with_email::
 If set to 0, then entries in changelog (subject of commits) are not followed by
@@ -70,9 +60,15 @@ changelog_do_not_remove_cherrypick::
 If set to 0, it will not remove from cherry picked commits the part "(cherry
 picked from commit ...)"
 
+tag_suffix::
+An optional specification of a suffix to append to all tags created by tito for this repo. Can be useful for situations where one git repository is inheriting from another, but tags are created in both. The suffix will be an indicator as to which repo the tag originated in. (i.e. tag_suffix = -mysuffix)
+
 
 KOJI
 ----
+
+WARNING: very experimental, and not tested against Fedora's Koji.
+
 autobuild_tags::
 If you use --koji-relase it will try to build src.rpm package in specified tags
 in koji.
@@ -89,10 +85,10 @@ Space separated list of packages, which should not be built in this tag.
 CVS
 ---
 cvsroot::
-Root of you Dist-CVS to checkout.
+Root of your CVS repository. (i.e. cvsroot = :ext:myuser@cvs.fedoraproject.org:/cvs/extra)
 
 branches::
-In which dist-cvs branch should be commited your spec file and patches.
+CVS branches to sync sources to, and build from.
 If you use zStreamTagger for EUS builds, use the format
  branches = BASE/EUS-VARIANT
 for example:
@@ -105,6 +101,7 @@ REQUIREMENTS
 tito::
 If tito is older then specified version, it will refuse to continue.
 
+
 BUILDERS
 --------
 
@@ -154,8 +151,8 @@ Tagger which increments zstream number in release. I.e. x.y.z-r%{dist}.Z+1
 It is used for EUS packages.
 
 tito.rheltagger.RHELTagger::
-Tagger which is based on ReleaseTagger and use Red Hat Enterprise Linux
-format of Changelog:
+Tagger which is based on ReleaseTagger and uses Red Hat Enterprise Linux
+changelog format:
 - Resolves: #1111 - description
 - Related: #1111 - description
 

tito.spec

@@ -39,6 +39,7 @@ git.
 a2x -d manpage -f manpage titorc.5.asciidoc
 a2x -d manpage -f manpage tito.8.asciidoc
 a2x -d manpage -f manpage tito.props.5.asciidoc
+a2x -d manpage -f manpage releasers.conf.5.asciidoc
 
 %install
 rm -rf $RPM_BUILD_ROOT
@@ -50,6 +51,7 @@ rm -f $RPM_BUILD_ROOT%{python_sitelib}/*egg-info/requires.txt
 %{__gzip} -c titorc.5 > %{buildroot}/%{_mandir}/man5/titorc.5.gz
 %{__gzip} -c tito.8 > %{buildroot}/%{_mandir}/man8/tito.8.gz
 %{__gzip} -c tito.props.5 > %{buildroot}/%{_mandir}/man5/tito.props.5.gz
+%{__gzip} -c releasers.conf.5 > %{buildroot}/%{_mandir}/man5/releasers.conf.5.gz
 %{__gzip} -c build.py.props.5 > %{buildroot}/%{_mandir}/man5/build.py.props.5.gz
 
 %clean
@@ -61,6 +63,7 @@ rm -rf $RPM_BUILD_ROOT
 %doc README.mkd AUTHORS COPYING
 %doc %{_mandir}/man5/titorc.5.gz
 %doc %{_mandir}/man5/tito.props.5.gz
+%doc %{_mandir}/man5/releasers.conf.5.gz
 %doc %{_mandir}/man5/build.py.props.5.gz
 %doc %{_mandir}/man8/tito.8.gz
 %{_bindir}/tito

titorc.5.asciidoc

@@ -4,7 +4,7 @@ include::man.asciidoc[]
 
 NAME
 ----
-titorc - Settings file for `tito`
+titorc - A user specific settings file for `tito`.
 
 
 SYNOPSIS
@@ -15,15 +15,10 @@ None
 
 DESCRIPTION
 -----------
-User preferences can be stored in files:
-
-`~/.spacewalk-build-rc`
+User preferences can optionally be stored:
 
 `~/.titorc`
 
-If `$HOME/.spacewalk-build-rc` exists, tito ignores `$HOME/.titorc`.
-Both files are optional.
-
 
 OPTIONS
 -------
@@ -34,13 +29,14 @@ execute --koji-release. For example:
 RPMBUILD_BASEDIR::
 Specifies a base directory for temp files, tarballs, and RPMs.
 If defined, and if the directory exists, `tito` will automatically
-create subdirectories as needed for rpmbuild(8).
+create subdirectories as needed for rpmbuild(8). Can be overridden
+on the fly with -o. The default output directory is /tmp/tito.
 
 HIDE_EMAIL::
-If set to something different from 0, it will not use you email address
-in changelog entry. I.e. instead of
+If set to something other than 0, your email address will not be used in
+changelog entries. I.e. instead of
  * Tue Feb 11 2011 Miroslav Suchy <msuchy@redhat.com> 0.3.0-2
-it will use:
+You will get:
  * Tue Feb 11 2011 Miroslav Suchy 0.3.0-2
 
 EXAMPLE