[ << LSR work ][Top][Contents][ Issues >> ]
[][ 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 section 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/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 section 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 section 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 file name 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 section 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 section Lifecycle of a merge request).
[ << LSR work ][Top][Contents][ Issues >> ]
[][ Up : LSR work ][]

<< Back to Documentation Index

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