In Contributor's Guide
Total Page：16
File Type：pdf, Size：1020Kb
LilyPond The music typesetter Contributor’s Guide The LilyPond development team ☛ ✟ This manual documents contributing to LilyPond version 2.21.82. It discusses technical issues and policies that contributors should follow. This manual is not intended to be read sequentially; new contributors should only read the sections which are relevant to them. For more information about different jobs, see Section “Help us” in Contributor’s Guide. ✡ ✠ ☛ ✟ For more information about how this manual fits with the other documentation, or to read this manual in other formats, see Section “Manuals” in General Information. If you are missing any manuals, the complete documentation can be found at http://lilypond.org/. ✡ ✠ Copyright ⃝c 2007–2020 by the authors. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections. A copy of the license is included in the section entitled “GNU Free Documentation License”. For LilyPond version 2.21.82 i Table of Contents 1 Introduction to contributing .................................. 1 1.1 Help us ................................................... ......................... 1 1.2 Overview of work flow ................................................... .......... 2 1.3 Summary for experienced developers ............................................... 2 1.4 Mentors ................................................... ........................ 3 2 Quick start................................................... ... 5 2.1 LilyDev................................................... ......................... 5 Installing LilyDev in VirtualBox ................................................... .. 5 Configuring LilyDev in VirtualBox ................................................... 7 2.2 Compiling with LilyDev................................................... ......... 8 2.3 Now start work! ................................................... ................ 9 3 Working with source code .................................... 10 3.1 Setting up ................................................... ..................... 10 3.1.1 Installing Git ................................................... ............. 10 3.1.2 Cloning and forking the repository ........................................... 10 3.1.3 Configuring Git ................................................... ........... 10 3.2 Git cheat sheet ................................................... ................ 11 Pulling recent changes ................................................... ........... 11 Viewing the history ................................................... .............. 11 Switching branches ................................................... .............. 11 Listing branches ................................................... ................. 12 Staging and committing files ................................................... ..... 12 Amending and reverting changes ................................................... 12 Uploading your branch for review ................................................... 12 Deleting branches ................................................... ................ 12 3.3 Lifecycle of a merge request ................................................... .... 13 3.3.1 Uploading a patch for review ................................................. 13 3.3.2 Automated and manual testing............................................... 13 3.3.3 Patch countdown ................................................... ......... 13 3.3.4 Merging to master ................................................... ........ 14 3.3.5 Abandoned patches ................................................... ....... 14 3.4 Writing good commit messages................................................... 14 3.5 Commit access................................................... ................. 15 3.6 Further Git documentation resources .............................................. 16 3.7 Repository directory structure ................................................... 16 3.8 Other repositories................................................... .............. 18 4 Compiling ................................................... .. 20 4.1 Overview of compiling ................................................... ......... 20 4.2 Requirements ................................................... .................. 20 4.2.1 Requirements for running LilyPond .......................................... 20 4.2.2 Requirements for compiling LilyPond......................................... 21 Fedora................................................... ........................ 21 Linux Mint ................................................... ................... 22 OpenSUSE ................................................... ................... 22 ii Ubuntu................................................... ....................... 23 Other ................................................... ........................ 23 4.2.3 Requirements for building documentation .................................... 24 4.3 Getting the source code ................................................... ........ 25 4.4 Configuring make ................................................... .............. 26 4.4.1 Running ./autogen.sh ................................................... ... 26 4.4.2 Running ../configure ................................................... ... 26 Configuration options ................................................... ......... 26 Checking build dependencies ................................................... .. 26 Configuring target directories ................................................... 27 4.5 Compiling LilyPond ................................................... ........... 27 4.5.1 Using make ................................................... ............... 27 4.5.2 Saving time with the -j option............................................... 28 4.5.3 Useful make variables ................................................... ..... 28 4.6 Post-compilation options ................................................... ....... 28 4.6.1 Installing LilyPond from a local build ........................................ 28 4.6.2 Generating documentation ................................................... 28 Documentation editor’s edit/compile cycle ....................................... 28 Building documentation ................................................... ...... 29 Building a single document ................................................... ... 29 Saving time with CPU_COUNT ................................................... .. 30 Installing documentation................................................... ...... 30 Building documentation without compiling ....................................... 30 4.6.3 Testing LilyPond binary ................................................... .. 31 4.7 Problems ................................................... ...................... 31 Compiling on MacOS X................................................... .......... 31 FreeBSD................................................... ......................... 32 International fonts ................................................... ............... 32 Using lilypond python libraries................................................... ... 32 4.8 Concurrent stable and development versions....................................... 32 4.9 Build system ................................................... .................. 33 5 Documentation work ......................................... 34 5.1 Introduction to documentation work .............................................. 34 5.2 \version in documentation files .................................................. 34 5.3 Documentation suggestions ................................................... .... 35 5.4 Texinfo introduction and usage policy ............................................. 36 5.4.1 Texinfo introduction ................................................... ...... 36 5.4.2 Documentation files ................................................... ....... 36 5.4.3 Sectioning commands ................................................... ..... 37 5.4.4 LilyPond formatting ................................................... ...... 38 5.4.5 Text formatting ................................................... ........... 40 5.4.6 Syntax survey................................................... ............. 40 Comments ................................................... .................... 40 Cross references ................................................... .............. 41 External links ................................................... ................ 41 Fixed-width font................................................... .............. 41 Indexing................................................... ...................... 42 Lists................................................... .......................... 43 Special characters................................................... ............. 43 Miscellany ................................................... .................... 43 5.4.7 Other text concerns ................................................... ....... 44 5.5 Documentation policy................................................... .......... 44 5.5.1 Books ................................................... .................... 44 iii 5.5.2 Section