Automatic Upgrade Helper
========================

This is a utility designed to be used in conjunction with the
OpenEmbedded build system (BitBake and OE-Core) in order to
automatically generate upgrades for recipes based on new versions being
published upstream.


Setup
-----

0. AUH needs all the dependencies listed for Yocto also requires git 
   configured because uses it to save upgrades, you need to have git
   user and email configured, example:

   $ git config --global user.name "Some Name"
   $ git config --global user.email "[email protected]"

1. Run the oe-init-build-env script to create a fresh build directory, solely
   for the purpose of running AUH:

   $ . ./oe-init-build-env build-auh

   Re-using existing build directories and configurations is not recommended
   as they may contains tweaks that will break AUH or make it behave in
   undesirable ways.

2. Prepare a configuration file, by default in $BUILDDIR/upgrade-helper/
   upgrade-helper.conf. A sample file is provided in AUH source tree;
   it can be used as-is, or tweaked further.

WARNING: if you are using the default maintainers.inc file supplied
         with Poky (in meta-yocto) and you don't set a
         maintainers_whitelist or (global_)maintainer_override in the
         upgrade-helper configuration as above, and you specify "-e all"
         on the command line, the script will automatically send out
         emails to the default maintainers. Please be careful not to
         do this :)

4. If you want to enable buildhistory (optional) you need to enable it in
upgrade-helper.conf, and also add the following lines to your conf/local.conf
file:

--------------- snip ---------------
INHERIT =+ "buildhistory"
BUILDHISTORY_COMMIT = "1"
--------------- snip ---------------

If upgrade is succesful buildhistory diff's are generated into
$BUILDDIR/upgrade-helper/work/recipe/buildhistory-diff.txt.

(Do not remove any other inherited class in the process).

5. If you want to enable testimage (optional) you need to enable in
upgrade-helper.conf also add the following lines to your conf/local.conf
file:

--------------- snip ---------------
INHERIT += "testimage"

# Add the following if your distro does not enable by default (poky does)
#DISTRO_FEATURES_append = " ptest"
--------------- snip ---------------

Also if you are running in a server without X11 session, you need to start
a vncserver example:

$ vncserver :1
$ export DISPLAY=:1

(Do not remove any other inherited class in the process).

Usage
-----

Some manual usage examples:

* To upgrade the xmodmap recipe to the latest available version:
    $ upgrade-helper.py xmodmap

* To upgrade the xmodmap recipe to a user specified version:
    $ upgrade-helper.py xmodmap -t 1.2.3

* To upgrade all recipes to latest available versions, without 
  sending any emails:
    $ upgrade-helper.py all

* To attempt to upgrade all recipes and automatically send email
  messages to maintainers for each attempted recipe as well as a
  status mail at the end, use:
    $ upgrade-helper.py -e all

The results of the AUH run (patches, logs and any other relevant information)
are then found in ${BUILDDIR}/upgrade-helper/<timestamp>. AUH will also
create recipe update commits from successful upgrade attempts in the layer tree.

If you wish to run the script on a regular basis, you can set up a cron
job; the "weeklyjob.sh" file distributed with this project is the basis
of a script you can call from a cron job and also provides an example
crontab line.

Maintenance
-----------

The code for this application is maintained by the Yocto Project.

The latest version of the code can always be found here:

  http://git.yoctoproject.org/cgit/cgit.cgi/auto-upgrade-helper/

Contributions are welcome. Please send patches / pull requests to
[email protected] with '[auh]' in the subject also CC the
current maintainer: Alex Kanavin <[email protected]>.

License
-------

This application is licensed under the GNU General Public License
version 2.0 or (at your option) any later version. Please see the
LICENSE file for further details.