X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;ds=sidebyside;f=Documentation%2Fdevel%2Fprogramming-work.itexi;h=1170949402c63c3427b4aa195b50d7f297a727fc;hb=3eb1e37e2e0b3966142cd04b85e30ab882308612;hp=a50ec6672389bc3e684488939aa64df8723b5f61;hpb=fe21ad2f87481ed825fbc513eff32bec83871386;p=lilypond.git diff --git a/Documentation/devel/programming-work.itexi b/Documentation/devel/programming-work.itexi index a50ec66723..1170949402 100644 --- a/Documentation/devel/programming-work.itexi +++ b/Documentation/devel/programming-work.itexi @@ -5,10 +5,11 @@ @menu * Overview of LilyPond architecture:: * LilyPond programming languages:: -* Programming without compiling:: -* Finding functions:: -* Code style:: -* Debugging LilyPond:: +* Programming without compiling:: +* Finding functions:: +* Code style:: +* Debugging LilyPond:: +* Adding or modifying features:: @end menu @node Overview of LilyPond architecture @@ -103,7 +104,7 @@ Interpretation of Computer Programs}, a popular textbook used to teach programming in Scheme is available in its entirety online. An introduction to Guile/Scheme as used in LilyPond can be found in the -Learning Manual, see @rlearning{Scheme tutorial}. +Learning Manual, see @rlearning{Scheme tutorial}. @subsection MetaFont @@ -564,7 +565,7 @@ LilyPond with debugging information. This is accomplished by running the following commands in the main LilyPond source directory. @example -./configure --disable-optimization +./configure --disable-optimising make @end example @@ -701,3 +702,139 @@ guile> (quit) The compilation of the .ly file will then continue. +@node Adding or modifying features +@section Adding or modifying features + +When a new feature is to be added to LilyPond, it is necessary to +ensure that the feature is properly integrated to maintain +its long-term support. This section describes the steps necessary +for feature addition. + +@subsection Write the code + +You should create a new git branch for writing the code, as that +will separate it from the master branch and allow you to continue +to work on small projects related to master. + +Please be sure to follow the rules for programming style discussed +earlier in this chapter. + +@subsection Write regression tests + +In order to demonstrate that the code works properly, you will +need to write one or more regression tests. These tests are +typically .ly files that are found in input/regression. + +Regression tests should be as brief as possible to demonstrate the +functionality of the code. + +Regression tests should generally cover one issue per test. Several +short, single-issue regression tests are preferred to a single, long, +multiple-issue regression test. + +Use existing regression tests as templates to demonstrate the type of +header information that should be included in a regression test. + +@subsection Write documentation + +Although it is not required, it is helpful if the developer can +write relevant material for inclusion in the Notation Reference. +If the developer does not feel qualified to write the documentation, +a documentation editor will be able to write it from the regression +tests. + +If the modification changes the input syntax so that inline snippets in +the documentation need to be changed, you will need to change the +snippets in both the english version of the documentation and any +translated versions. If you do not change the snippets in all +translations, older versions of the snippet may be included +when the documentation is built. + +If lsr snippets need to be changed, the snippet should be copied to +input/new and modified there. The portions of the snippet that +are added by makelsr.py should be removed. The changed snippet +will then be included in all versions of the documentation. + +If non-snippet text is changed in the english documentation, no +corresponding changes should be made in the translated documentation. + +@subsection Write convert-ly rule + +If the modification changes the input syntax, a convert-ly rule +should be written to automatically update input files from older +versions. + +convert-ly rules are found in python/convertrules.py + +If possible, the convert-ly rule should allow automatic updating +of the file. In some cases, this will not be possible, so the +rule will simply point out to the user that the feature needs +manual correction. + +@subsection Write NEWS entry + +An entry should be added to the NEWS file to describe the feature +changes to be implemented. This is especially important for changes +that change input file syntax. + +Hints for NEWS file entries are given at the top of the NEWS file. + +New entries in NEWS go at the top of the file. + +The NEWS entry should be written to show how the new change +improves LilyPond, if possible. + +@subsection Verify regression test + +In order to avoid breaking LilyPond, it is important to verify that +the regression tests all succeed. This process is described in +@ref{Regression tests}. + +@subsection Post patch for comments + +For any change other than a minor change, a patch set should be +posted on Rietveld for comment. + +The patch set is posted by issuing the following command, after +first committing all changes: + +@example +git-cl upload +@end example + +@noindent +where is the SHA1 ID of the commit to be used +as a reference source for the patch (generally, this will be the +SHA1 ID of origin/master). + +After prompting for an email and a password, the patch set will be +posted to Rietveld. + +An email should then be sent to lilypond-devel, with a subject line +starting with PATCH:, asking for comments on the patch. + +As revisions are made in response to comments, successive patch sets +for the same issue can be uploaded by reissuing the git-cl command. + +@subsection Push patch + +Once all the comments have been addressed, the patch can be pushed. + +If the author has push privileges, the author will push the patch. +Otherwise, a developer with push privileges will push the patch. + +@subsection Closing the issues + +Once the patch has been pushed, all the relevant issues should be +closed. + +On Rietveld, the author should log in an close the issue either by +using the @q{Edit Issue} link, or by clicking the circled x icon +to the left of the issue name. + +If the changes were in response to a feature request on the Google +issue tracker for LilyPond, the author should change the status to +@q{Fixed_x_y_z} where the patch was fixed in version x.y.z. If +the author does not have privileges to change the status, an email +should be sent to bug-lilypond requesting the BugMeister to change +the status.