7.4 LSR to Git

Introduction

Snippets used in the documentation are in ‘$LILYPOND_GIT/Documentation/snippets’. This directory contains a complete set of the snippets in the LSR which are tagged with ’docs’. The exact method for getting them there is described below, but in essence they come from downloading a tarball from the LSR and importing into the directory using the makelsr script.

Any snippets which are too bleeding edge to run on the LSR (which uses a stable development version) are put into ‘$LILYPOND_GIT/Documentation/snippets/new’. Once the LSR has been upgraded so that these will run, then they are transferred to the LSR and deleted from ‘/snippets/new’.

’Git’ is the shorthand name for the Git repository that contains all the development code. For further information on setting this up see, Working with source code. An alternative to setting up a Git repository for people wanting to do LSR work is to get the source code from https://lilypond.org/website/development.html.

Importing the LSR to Git

1. Make sure that convert-ly script and the lilypond binary are a bleeding edge version – the latest release or even better, a fresh snapshot from Git master, with the environment variable LILYPOND_BUILD_DIR correctly set up, see Environment variables.
2. Start by creating a list of updated snippets from your local repository. From the top source directory, run:

   scripts/auxiliar/makelsr.py

   Commit the changes and make a patch. Check the patch has nothing other than minor changes. If all is good and you’re confident in what you’ve done, this can be merged directly to master.

3. Next, download the updated snippets and run makelsr.py against them. From the top source directory, run:

   wget http://lsr.di.unimi.it/download/lsr-snippets-docs-`date +%F`.tar.gz tar -xzf lsr-snippets-docs-`date +%F`.tar.gz make -C $LILYPOND_BUILD_DIR scripts/auxiliar/makelsr.py lsr-snippets-docs-`date +%F`

   where date +%F gives the current date in format YYYY-MM-DD (the snippets archive is usually generated around 03:50 CET, you may want to use date -d yesterday +%F instead, depending on your time zone and the time you run this commands sequence). make is included in this sequence so that makelsr can run lilypond and convert-ly versions that match current source tree; you can select different binaries if desired or needed, to see options for this do

   scripts/auxiliar/makelsr.py --help

4. Follow the instructions printed on the console to manually check for unsafe files. These are:

   Unsafe files printed in lsr-unsafe.txt: CHECK MANUALLY! git add Documentation/snippets/*.ly xargs git diff HEAD < lsr-unsafe.txt

   First, it’s important to check for any added files and add them to the files git is tracking. Run git status and look carefully to see if files have been added. If so, add them with git add.

   As the console says, makelsr creates a list of possibly unsafe files in ‘lsr-unsafe.txt’ by running lilypond against each snippet using the -dsafe switch. This list can be quite long. However, by using the command xargs git diff HEAD < lsr-unsafe.txt git will take that list and check whether any of the snippets are different from the snippet already in master. If any is different it must be checked manually VERY CAREFULLY.

   Note: Somebody could sneak a #'(system "rm -rf /") command into our source tree if you do not do this! Take this step VERY SERIOUSLY.

   If there is any doubt about any of the files, you are strongly advised to submit a merge request to get review.

5. If a review is not needed, merge to master after the changes passed automatic testing.

Note that whenever there is a snippet in ‘Documentation/snippets/new’ and another from the LSR with the same file name, makelsr.py will overwrite the LSR version with the one from ‘Documentation/snippets/new’.

This document was generated by gub on July 13, 2020 using texi2html 1.82.