Working With Package Branches

A Package Branch is a ‘child’ of a Package resource. It is a means of having multiple ways to build a ‘package’, but that are all related to a package. Take for example an upstream developer. They have the upstream source, and need to build official upstream packages for RPM based distributions (Red Hat, Fedora, Etc) and DEB based distributions (Debian/Ubuntu). Both of these builds require a different build_handler to know how to build from the source. The VCS source repo may very well be the same exact URL, however how it is built is different requiring a different package-branch definition.

Package Branches require project-admin privileges, meaning to create and modify packages the user must be a part of the project’s admin group.

Note: The below examples assume that you have set your ‘current-project’ to ‘my-project’, so as to not have to pass the ‘–project’ option with every command. This can be done as:

$ mf workon my-project

Creating a Package Branch

$ mf package-branch create \
    -l git17.rpm \
    --package git17 \
    --build-handler rpm \
    --release el4,el5

A number of items are inherited from the parent ‘package’ such as user, and group ownership. Also, the ‘url’ of the package branch is [by default] auto generated based on the default template of the project ‘vcs_handler’. If the template does not provide a proper url (see mf project-branch show) then it can be overridden with the ‘–url’ option.

Note: The ‘releases’ default to all available releases based on the build handler. If you do not specify a release, or set –release=’’ then the package branch will build against all releases configured for the build handler. You can then ‘exclude’ releases from that list. This allows all package branches to always build for the latest releases as they are added by the MF administrator.

$ mf package-branch create \
    -l git17.rpm \
    --package git17 \
    --build-handler rpm \
    --excluded-release=el4,el5,el6

The above will use the default releases, but exclude [‘el4’, ‘el5’, ‘el6’] and just build against the remaining releases.

Updating a Package Branch

$ mf package-branch update git17.rpm \
    --url=git://example.com/git17.git \
    --vcs-branch='1_7_X' \
    --build-prefix='mfbuild/'

Note: Members of the package group have the same permission as the owner of the package. It can be looked at as, the owner or ‘user’ of the package is the primary owner, and members of the package’s group are secondary owners even though they both have the same permissions.

Deleting a Package Branch

$ mf package-branch delete git17.rpm

Listing Package Branches

List all package branches under ‘my-project’, that I own or whose group I belong to:

$ mf package-branch listall
git17.rpm
git17.deb
php52.rpm
php52.deb

List all package branches under ‘my-project’, that I own or whose group I belong to, but filter results:

$ mf package-branch listall -f php
php52.rpm
php52.deb

List all package branches under ‘my-project’ that I own:

$ mf package-branch listall --mine
git17.rpm
git17.deb

List all package branches under ‘my-project’:

$ mf package listall --all
mysql50.rpm
mysql50.deb
mysql51.rpm
mysql51.deb
git17.rpm
git17.deb
php52.rpm
php52.deb

$ mf package listall --all -f mysql
mysql50.rpm
mysql50.deb
mysql51.rpm
mysql51.deb

Showing Data For a Package Branch

$ mf package-branch show git17.rpm

          Label | git17.rpm
        Summary | Fast Version Control System
          Owner | ius-admin
        Project | my-project
    Group Owner | ius-coredev
 Parent Package | git17
    Source Name | git
     Created On | 2011-01-27 10:59:15
    Last Update | 2011-01-27 11:21:55
            URL | git://repoman.rackspace.com/git17
     VCS Branch | 1_7_X
  Build Handler | rpm
    Build Count | 0
Build on Commit | False

       Releases | el5
                  el6

       Excluded | el4

Note: The ‘url’ is determined by the project’s vcs_handler. Each vcs handler has a url template it uses to determine the package source location. For this reason one must take care in organizing the source repositories to ensure it matches up with what MonkeyFarm is looking for.

Explanation of Options

Required Options:

-l/–label

The label of the package branch (how it is identified).

—package

The label of the parent package resource.

Additional Options:

--url

A URL to a VCS repo to override the default.

—vcs-branch

Signifies an alternate branch to use within the vcs repo (i.e. git).

—build-on-commit

Currently this does nothing, but is intended to be used by external applications. For example, and external app can pull data from a VCS repo and when changes are committed, whether this setting is enabled or not, can submit a build.

—build-prefix

The build prefix tells the build handler where to build from. For example, some projects may prefer to have their packaging ‘sources’ separate from their main project source, however some may wish to combine the two. For build handlers to be able to function they rely on a specific directory structure to find the files it needs to build. Therefore, for a project wanting to combine their project source and build source, they could create a build prefix where the files for the build handler would reside within the checked out source tree.

—release

The release you want this package to build against. Can be a comma separated list (no spaces). Defaults to build_handler.releases.

—excluded-release

The release you want to exclude, useful when ‘–release’ is blank and therefore using the build_handler.releases as default. Can be a comma separated list (no spaces).