[ << LSR work ][Top][Contents][ Issues >> ]
[ < The makelsr.pl script ][ Up : LSR work ][]

7.5 LSR to Git

Introduction

Snippets used in the documentation are in ‘$LILYPOND_GIT/Documentation/snippets/’. This directory contains a set of all snippets in the LSR that are tagged with ‘docs’. An import is done with the makelsr.pl script, which downloads a complete database dump of the LSR to update this directory.

Snippets that are too new to be run on the LSR (which uses a stable LilyPond version) are put into ‘$LILYPOND_GIT/Documentation/snippets/new/’. Once the LSR gets upgraded to a LilyPond version that can actually compile them, they are transferred to the LSR and deleted from ‘snippets/new/’.

‘Git’ is the shorthand name for LilyPond’s Git repository, which 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. However, we don’t recommend this since it doesn’t allow easy submission of patches as merge requests.

Importing the LSR to Git

  1. Make sure that the convert-ly script is a bleeding edge version – the latest development release, or even better, freshly compiled from Git master, with the environment variable LILYPOND_BUILD_DIR correctly set up (see Environment variables) in case your build directory isn’t ‘$LILYPOND_GIT/build/’.
  2. Check the other prerequisites necessary for executing the makelsr.pl script (see The makelsr.pl script).
  3. If you are using a git repository, create and check out a branch, for example 
    git checkout -b lsr-import
  4. From the top source directory, execute 
    scripts/auxiliar/makelsr.pl

    Say ‘scripts/auxiliar/makelsr.pl --help’ to find out how to modify this call; for example, command line option ‘--dump file’ makes the script use a locally stored dump file.

  5. Carefully check the output of the script for warnings and errors, then carefully check the file differences in the git repository. ‘git diff’ is your friend.
  6. Rebuild the documentation. If some snippets from ‘Documentation/snippets/’ cause the documentation compilation to fail, try the following steps to fix it.
    • Look up the snippet filename ‘foo.ly’ in the error output or log file, then fix the file ‘Documentation/snippets/foo.ly’ to make the documentation build successfully.
    • Determine where it comes from by looking at its first two lines, e.g., run 
      head -2 Documentation/snippets/foo.ly
    • If the snippet comes from the LSR, also apply the fix to the snippet in the LSR and send a notification email to an LSR editor with CC to the development list, see Adding and editing snippets.

      Note that the failure may sometimes not be caused by the snippet in the LSR but by LilyPond syntax changes that convert-ly can’t handle automatically. Such files must be added to the ‘new/’ directory.

    • If the snippet comes from ‘Documentation/snippets/new/’, apply the fix in ‘Documentation/snippets/new/foo.ly’ and run makelsr.pl as follows: 
      scripts/auxiliar/makelsr.pl --new

      Then, inspect ‘Documentation/snippets/foo.ly’ to check that the fix has been well propagated.

    • If the build failure was caused by a translation string, you may have to fix some ‘Documentation/lang/texidocs/foo.texidoc’ files instead.
  7. When you are done, commit your changes to your Git branch and create a merge request (see Lifecycle of a merge request).
[ << LSR work ][Top][Contents][ Issues >> ]
[ < The makelsr.pl script ][ Up : LSR work ][]

<< Back to Documentation Index

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