14.4 Patchy

Introduction

Patchy is a set of Python scripts to automate two administrative tasks:

Installing Patchy

To install Patchy, you should do the following:

  1. Create a new user on your box to run Patchy; this is a security step for your own protection. It is recommended that this should not be an administrator. New users are created from System; Administration; Users and Groups.
  2. Get the Patchy scripts from
    https://github.com/gperciva/lilypond-extra/
    

    Patchy is in the ‘patches/’ directory.

  3. Put the scripts and Python libraries contained in ‘patches’ in a sensible place on your system; this can be done by appending ‘patches/’ full path to the PATH of the user that runs Patchy.
  4. Create a new git repository with
    git clone git://git.sv.gnu.org/lilypond.git
    

    This will create a directory called lilypond with the repo in it. Make sure it’s where you want it and name it lilypond-git (assuming you want to follow the standard naming conventions).

  5. Create environment variables LILYPOND_GIT and LILYPOND_BUILD_DIR, see Environment variables.
  6. Run Patchy once to set up config files, answer ‘n’ when it asks for going on, unless the default config file happens to suit your setup:
    lilypond-patchy-staging.py
    
  7. Edit ‘$HOME/.lilypond-patchy-config’ to provide the location of your local lilypond Git repository, working directories for your build directory, your results directory, compiler options and notification method. If you don’t want to use email notification, then delete everything after smtp_command:.
  8. Ensure that your new user has git push access. Follow the instructions in the CG at Commit access. Do not set password protection for the key — if you do you will not be able to run patchy unattended.

lilypond-patchy-staging.py

lilypond-patchy-staging.py is run with

python lilypond-patchy-staging.py

Not much appears to happen except you can see a lot of CPU gets used if you open System Monitor. There’s not much point running lilypond-patchy-staging.py unless there is something in staging to be merged to master, however, if there’s nothing new in staging then the script won’t waste resources by compiling anything.

The script fetches the current patches in staging and runs make, make test and make doc to ensure that all of these complete error-free. If you have set Patchy up to use email, it emails its results to you. If you haven’t, then you can view them in a logfile. It also merges staging into master.

Note: in case the build fails, do not try to push fixes on top of staging branch, for details see Pushing to staging.

When you have run Patchy a few successful times with email sending, you are ready for running it as a cron job. First, make sure you have the following in ‘$HOME/.lilypond-patchy-config’ to avoid email flood:

[notification]
notify_non_action = no

Then, assuming Patchy run with user account patchy, write the following to ‘$HOME/lilypond-patchy.cron’, adapting it as necessary (the /2 means “run this every 2 hours”):

02 0-23/2 * * * /home/patchy/git/lilypond-extra/patches/lilypond-patchy-staging.py

Note: cron will not inherit environment variables from your main setup, so you must re-define any variables inside ‘$HOME/lilypond-patchy.cron’. For instance, LILYPOND_GIT may need to be defined if git_repository_dir is not correctly set in ‘$HOME/.lilypond-patchy-config’.

Finally, install the cron job (you may need superuser privileges for this):

crontab -u patchy /home/patchy/lilypond-patchy.cron

test-patches.py

test-patches.py prepares a regtest comparison for a human to quickly glance at, to determine if the patch is ready for a review. After looking at the comparison (or the lack of a comparison in the case of problems), run accept-patch.py or reject-patch.py.

Once a patch has gotten a "LGTM" from Patchy, it should be reviewed by relevant developers, and if it passes this, it can be considered for countdown (see Commits and patches) and pushing to staging (see Pushing to staging).


LilyPond — Contributor’s Guide v2.19.4 (development-branch).