Working With Tags
-----------------

Tags are the primary means of organizing builds.  Common tags are 'testing',
'development', 'stable'.  MonkeyFarm provides a number of features based on
tags that can be really useful.  Here are a few:

    requires_admin
        The tag requires the user to be part of the projects admin_group
        
    manage_repo
        Manage a repository of files when builds are tagged
        
    include_in_builds
        Allows build_handlers to detect this setting, and configure builds
        to also include files from the managed repo (i.e. the mock 
        build_handler dynamically adds the projects tag repo into the mock
        configs).
    
    close_on_tag
        Close builds (and potentially bugs) when the builds is tagged.
        
    locked
        Allows an admin to lock the tag before performing other operations 
        (such as moving builds from one tag to another)
    
    only_latest
        Removes older builds from the tag, when a newer build with the same
        package is tagged.


Tags, along with the API interface allow organizations to automate certain
operations.  For example, a common use would be the following tags:

    testing-candidate
        All users are allowed to tag a build into this tag.
        
    testing
        An automation script can then automate moving all builds from
        testing-candidate into testing (which requires admin privileges).  At
        the same time the automation script can pull down the files for the
        new builds in testing, and generate an external repository for official
        testing.
        
    stable-candidate
        After some time in testing, the user can then tag a build as
        stable-candidate signifying that it has passed testing and can be 
        pushed to stable.
        
    stable
        An automation script then moves all tasks from stable-candidate, to
        stable... as well as untags the task from testing.
        
This is just a common scenario... the possibilities are only limited by the 
users imagination.


Creating a Tag
^^^^^^^^^^^^^^

.. code-block:: text
    
    $ mf tag create -l testing-candidate
    
    $ mf tag create -l testing --requires-admin=True
    
    $ mf tag create -l stable-candidate
    
    $ mf tag create -l stable --requires-admin=True --manage-repo=True
    
    
Updating a Tag
^^^^^^^^^^^^^^

.. code-block:: text

    $ mf tag update stable --run-createrepo=True \
                           --close-on-tag=True \
                           --only-latest=True \
                           --include-in-builds=True

Deleting a Tag
^^^^^^^^^^^^^^

.. code-block:: text

    $ mf tag delete testing-candidate


Listing Tags
^^^^^^^^^^^^

List all tags for a project:

.. code-block:: text

    $ mf tag listall
    
    # with a filter
    $ mf tag listall -f stable
    

Move All Builds From One Tag To Another
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: text

    $ mf tag move-builds stable-candidate --tag stable

    
*Note: The move-builds operation also returns 'untagged_builds' in its JSON
return data.  These are all the builds that were untagged from the destination
tag because of the 'only_latest' setting meaning they were older than a new
build.*