* Meta-policy for this document::
* Environment variables::
* Meisters::
-* Automated testing with Patchy::
+* Managing Staging and Master branches with Patchy::
* Administrative mailing list::
* Grand Organization Project (GOP)::
* Grand LilyPond Input Syntax Standardization (GLISS)::
@node Meisters
@section Meisters
-We have four jobs for organizing a team of contributors:
+We have four primary jobs to help organize all our contributors:
+
+@unnumberedsubsec The Bug Meister
+
+The Bug Meister's responsibilities are:
@itemize
@item
-Bug Meister: trains new Bug Squad volunteers, organizes who works
-on which part of their job, checks to make sure that everything is
-running smoothly, and has final say on our policy for Issues.
+To organize the individual Bug Squad volunteers, making sure that
+each member is aware of their responsibilities. See
+@ref{The Bug Squad}.
-Currently: Colin H
+@item
+To train new Bug Squad volunteers in the Issue Tracker process. See
+@ref{Issues}.
@item
-Doc Meister: trains new doc editors/writers, organizes who works
-on which part of the job, checks to make sure that everything is
-running smoothly, and has final say on our policy for
-Documentation. Also includes LSR work.
+To have the final say on our policies for Issues and their
+classification. See @ref{Issue classification}.
-Currently: None
+@end itemize
-@item
-Translation Meister: trains new translators, updates the
-translation priority list, and handles merging branches (in both
-directions).
+Current Bug Meister: Colin Hall @email{bug-lilypond@@gnu.org}
-Currently: Francisco
-@end itemize
+@unnumberedsubsec The Doc Meister
+The Doc Meister's responsibilities are:
-@node Automated testing with Patchy
-@section Automated testing with Patchy
+@itemize
-@menu
-* Overview of Patchy::
-* Patchy requirements::
-* Installing Patchy::
-* Configuring Patchy::
-* Running the scripts::
-* Automating Patchy::
-* Troubleshooting Patchy::
-@end menu
+@item
+To train new volunteers in our Documentation style and policy,
+including organizing LilyPond Snippet Repository (LSR) work.
-@node Overview of Patchy
-@subsection Overview of Patchy
+@item
+To organize the individual volunteers -- who does what on which job --
+and to check that everything is running smoothly.
+
+@item
+To have final say on any Documentation policy. See
+@ref{Documentation policy}.
+
+@end itemize
-Patchy is a set of Python scripts used for testing patches or testing &
-pushing new commits added to @code{remote/origin/staging} to
-@code{remote/origin/master}.
+Current Doc Meister: None
-No programmatic skill is required to run either of the scripts; although
-knowledge of compiling LilyPond and its documentation along with
-understanding how to configure the @var{PATH} environment of your
-computer is required. See @ref{Working with source code}.
-The two scripts that are used for each function are:
+@unnumberedsubsec The Patch Meister
+
+The Patch Meister's responsibilities are:
@itemize
+
@item
-@code{test-patches.py}. This script tests issues labelled as
-@qq{Patch-New} on the LilyPond issue tracker. Part of the testing
-process involves running the regression tests, so this script always
-requires some human intervention in order to visually check for any
-differences that may be present after a successful test has occurred.
+To keep track of all patches submitted for testing and review. This
+includes scanning the bug and dev email lists looking for any patches
+submitted by @q{random} contributors and advising them on how to submit
+a patch for testing and review. See @ref{Uploading a patch for review}
+and @ref{The patch review cycle}.
@item
-@code{lilypond-patchy-staging.py}. This script checks for any new
-commits in @code{remote/origin/staging}, makes sure that the new HEAD
-compiles along with all the LilyPond documentation. Then finally
-pushing to @code{remote/origin/master}. This script can be run and left
-unattended, requiring no human intervention.
+To makes sure that any patch submitted has a corresponding Issue Tracker
+and Rietveld Issue created for it before it enters the testing and
+review process. See @ref{Issues}.
+
+@item
+Updates all Issue statuses for all patches that are currently in the
+testing and review process periodically -- currently every 3 - 4 days.
+See @ref{Patch handling}.
@end itemize
-Both of the scripts can be run independently of each other and it is not
-necessary to be able to run both. So if you wanted to contribute to
-LilyPond development, for example by @emph{just} testing patches then
-this would still be a helpful contribution to LilyPond's development.
+@warning{The Patch Meister's role is a purely administrative one and no
+programming skill or judgement is assumed or required.}
-Patchy can also be configured to send emails after each successful (or
-unsuccessful) operation. This is not a requirement and is turned off
-by default.
-
-@c Need to explain in more detail how to set up Patchy for email but
-@c as I don't use myself it I have no experience - JL
+Currently: James Lowe @email{pkx@@gnu.org}
-@node Patchy requirements
-@subsection Patchy requirements
+@unnumberedsubsec The Translation Meister
-@subsubsubheading Testing new patches
+The Translation Meister's responsibilities are:
@itemize
@item
-A full local copy of the source code. See
-@ref{Working with source code}.
+To train new documentation translators in the translation process. See
+@ref{Translating the documentation}.
@item
-All the software needed for compiling LilyPond @emph{and} the
-documentation. Although being able to build the full set of LilyPond's
-manuals is not mandatory for testing (most) patches, part of the patch
-testing process requires that the regression tests are run and it is
-this that requires the software normally used for compiling
-documentation. See @ref{Compiling}.
+To update the translation priority list and handle the merging of the
+translation branches (in both directions).
@item
-Commit access is @emph{not} required to test patches, but a valid login
-to @uref{http://code.google.com/} @emph{is}.
+To have final say on any Translation management policies. See
+@ref{Translating the documentation}.
-@noindent
-Note that a google account does not need to be a Gmail account; you can
-use @emph{any} email address for your google account when you sign up.
+@end itemize
-@warning{In order for @code{patchy} to work as expected, your Google
-Account Settings must have the @q{Access for less secure apps} set to
-@q{Allowed}. This is normally the default setting.}
+Currently: Francisco Vila @email{translations@@lilynet.net}
-@end itemize
-@subsubsubheading Testing & pushing new commits
+@node Managing Staging and Master branches with Patchy
+@section Managing Staging and Master branches with Patchy
+
+@ignore
+The script 'test-patches.py' does not currently works with Allura.
+@end ignore
+
+@menu
+* Overview of Patchy::
+* Patchy requirements::
+* Installing Patchy::
+* Configuring Patchy::
+* Running the script::
+* Automating Patchy::
+* Troubleshooting Patchy::
+@end menu
+
+@node Overview of Patchy
+@subsection Overview of Patchy
+
+No programmatic skill is required to run Patchy; although knowledge of
+compiling LilyPond and its documentation along with understanding how to
+configure the @var{PATH} environment of your computer is required. See
+@ref{Working with source code}.
+
+The script @code{lilypond-patchy-staging.py} checks for any new commits
+in @code{remote/origin/staging}, makes sure that the new HEAD compiles
+along with all the LilyPond documentation. Then finally pushing to
+@code{remote/origin/master}. This script can be run and left
+unattended, requiring no human intervention.
+
+Patchy can also be configured to send emails after each successful (or
+unsuccessful) operation. This is not a requirement and is turned off
+by default.
+
+@c Need to explain in more detail how to set up Patchy for email but
+@c as I don't use myself it I have no experience - JL
+
+
+@node Patchy requirements
+@subsection Patchy requirements
@itemize
@item
Commit access @emph{is} required to test and push new commits, but a
-valid login to @uref{http://code.google.com/} is @emph{not}. See
+valid login to @uref{https://sourceforge.net} is @emph{not}. See
@ref{Commit access}.
@end itemize
@ref{Environment variables}.
@item
-To save being prompted for your login and password to
-@uref{http://code.google.com/} when testing patches. create a
-@emph{plain-text} file in your Patchy user's @code{$HOME} directory
-called @code{.lilypond-project-hosting-login} containing your login and
-password, each on a separate line.
-
-@example
-joe_smith123@@gmail.com
-mYp455w0rd!
-@end example
-
-@item
-Manually run either the @code{test-patches.py} or
-@code{lilypond-patchy-staging.py} scripts and when prompted:
+Manually run either the @code{lilypond-patchy-staging.py} script and
+when prompted:
@smallexample
Warning: using default config; please edit /home/joe/.lilypond-patchy-config
@end itemize
-Each completed patch test will also generate its own directory in
-@file{/tmp/...} labelled with the tracker issue number prefixed by
-@code{show-}.
-@example
-\tmp\show-3446
-@end example
-
-Both the scripts create clones of @code{staging} and @code{master}
+The script creates a clones of @code{staging} and @code{master}
branches (prefixed with @code{test-}) with a third branch, called
@code{test-master-lock} used as a check to protect against two or more
instances of Patchy being run locally at the same time.
-@node Running the scripts
-@subsection Running the scripts
-
-@subsubsubheading Testing & pushing new commits
+@node Running the script
+@subsection Running the script
@code{lilypond-patchy-staging.py} is run @emph{without} any arguments.
It then checks to see if @code{remote/origin/staging} is
the Developers List <lilypond-devel@@gnu.org> for advice.}
-@subsubsubheading Testing new patches
-
-When run without any argument, @code{test-patches.py} will check
-@uref{http://code.google.com/p/lilypond/issues/list} for all tracker
-issues that are marked with the label @code{Patch-new}. It then scrapes
-the issue, looking for the last Rietveld URL entered. It then downloads
-the patch file and applies it to @code{test-master}.
-
-Here is an example where two tracker issues labeled as @code{Patch-new}
-were detected:
-
-@smallexample
-...
-issues [4007, 4008]
-Trying issue 4007
-Found url: http://codereview.appspot.com/112210043
-Found patch: 4007,/home/joe/lilypond-git/issue112210043_1.diff,
-Trying issue 4008
-Found url: http://codereview.appspot.com/115770043
-Found patch: 4008,/home/joe/lilypond-git/issue115770043_1.diff,
-Fetching, cloning, compiling master.
-...
-@end smallexample
-
-If run no tracker items with the @var{Patch-New} label are found it will
-report:
-
-@example
-issues []
-@end example
-
-The script can also be run using the tracker issue number(s) as an
-argument regardless if the @var{Patch-New} label has been assigned;
-
-@example
-test-patches.py 4006
-@end example
-
-or
-
-@example
-test-patches.py 4006 3992 4020
-@end example
-
-The script then checks to see if any previously
-@code{make test-baseline}s have been generated and if the commit ID of
-@code{remote/origin/master} is different from that previously completed
-test.
-
-@noindent
-If no previous @code{make test-baseline} test is discovered or if the
-commit ID of @code{remote/origin/master} has changed, then a new
-@code{make test-baseline} will run first automatically before the patch
-is tested:
-
-This shows when the commit ID has changed:
-
-@smallexample
-...
-(UTC) Begin LilyPond compile, previous commit at 3f92dcb2c81dcd2755542b57a0a5f2039f29a211
-Merged master, now at: 4726764cb591f622e7893407db0e7d42bcde90d9
- Success: ./autogen.sh --noconfigure
- Success: /tmp/lilypond-autobuild/configure --disable-optimising
- Success: nice make clean
- Success: nice make -j3 CPU_COUNT=3
- Success: nice make test-baseline -j3 CPU_COUNT=3
- Success: nice make doc -j3 CPU_COUNT=3
- Success: nice make doc-clean
-...
-@end smallexample
-
-@noindent
-If a previous regression test @emph{is} discovered @emph{and} if the
-commit ID of @code{remote/origin/master} has not changed, then the patch
-will be tested against the previous @code{make test-baseline} without
-the need to re-generate a new one:
-
-@smallexample
-...
-issues [4009]
-Trying issue 4009
-Found url: http://codereview.appspot.com/110540043
-Found patch: 4009,/home/joe/lilypond-extra/patches/issue110540043_1.diff,
-Fetching, cloning, compiling master.
-(UTC) Begin LilyPond compile, previous commit at 4726764cb591f622e7893407db0e7d42bcde90d9
- Success: No new commits in master
-Using test baseline from previous build.
-...
-@end smallexample
-
-The patch is then applied and a @code{make} and @code{make check} are
-run. A full @code{make doc} is also run if the
-@file{.lilypond-patchy-config} file has been edited accordingly;
-
-@smallexample
-...
-Issue 4009:
-Issue 4009: Testing patch issue110540043_1.diff
- Success: git apply --index /home/joe/lilypond-git/issue112210043_1.diff
- Success: ./autogen.sh --noconfigure
- Success: /tmp/lilypond-autobuild/configure --disable-optimising
- Success: nice make clean
- Success: nice make -j3 CPU_COUNT=3
- Success: nice make check -j3 CPU_COUNT=3
- Success: nice make doc -j3 CPU_COUNT=3
-...
-@end smallexample
-
-Once all the tests have run (successfully or not), the script will clean
-up from the previous patch and, if required, start testing the next
-issue;
-
-@smallexample
-...
-Issue 4007: Cleaning up
- Success: nice make test-clean
- Success: nice make doc-clean
- Success: nice make clean
- Success: git reset --hard
-Issue 4007: Done.
-Issue 4008:
-Issue 4008: Testing patch issue115770043_1_diff
- Success: git apply --index /home/joe/lilypond-git/issue115770043_1.diff
- Success: ./autogen.sh --noconfigure
-...
-@end smallexample
-
-and so on.
-
-@subsubsubheading Checking the regression test results
-
-Assuming the patch passed all the @code{make} tests, the regression
-differences will be located in the @file{/test-results/} directory
-within the build location for the patch issue number;
-
-@example
-/tmp/show-4007/test-results/
-@end example
-
-Open @file{index.html} in a browser of your choice to view any
-differences.
-
-@noindent
-Alternatively if the Firefox browser is installed, then the regression
-test results can be opened by calling the appropriate
-@file{show-regtests-} file located in the auto-compile log location;
-
-@example
-sh ~/lilypond-auto-compile-results/show-regtests-4007
-@end example
-
-See @ref{Regression tests}.
-
-@subsubsubheading Reporting test results
-
-Once a patch has been tested and the regression tests have been
-manually checked, the tracker can be updated manually by editing the
-tracker issue directly in the web browser or by using two additional
-python scripts that are included as part of the Patchy suite.
-
-@unnumberedsubsubsec For patches that have passed
-
-Use the @code{accept-patch.py} script and run it with the Google issue
-tracker number (not the Rietveld issue number) as an argument;
-
-@example
-accept-patch.py 4007
-@end example
-
-This will automatically update the tracker issue with the phrase
-@qq{Patchy the autobot says: passes tests.}.
-
-@noindent
-It is also possible to add additional information to the default
-message by adding a second argument within double-quote marks.
-
-@example
-accept-patch.py 4007 "This also includes a full documentation build."
-@end example
-
-The tracker issue's label is then changed automatically to
-@qq{Patch-review}.
-
-@unnumberedsubsubsec Patches that have failed
-
-Use the @code{reject-patch.py} script and run it with the Google issue
-tracker number (not the Rietveld issue number) as an argument but you
-@emph{must} also include a second argument, in double-quotes, stating
-the reason the patch has been rejected;
-
-@example
-reject-patch.py 4007 "Fails the 'make check' test."
-@end example
-
-Once the @code{reject-patch.py} script has been run, the tracker issue's
-label is changed automatically to @qq{Patch-Needs_work}.
-
-
@node Automating Patchy
@subsection Automating Patchy
The following is a list of the most common messages that the scripts
may report with explanations.
-@itemize
-
-@item
-@example
-issues []
-@end example
-
-@itemize
-
-@item
-There are currently no tracker issues with the @code{Patch-New} status.
-
-@item
-If specific tracker issue number has been used as an argument when
-running @code{test-patches.py}, then the issue contains no URL to
-Rietveld.
-
-@end itemize
-
-@item
@smallexample
this Git revision has already been pushed by an operator other than this Patchy.
@end smallexample
in staging.
@item
-You may also see this on your local machine if the auto-build files
-have been deleted and this computer has previously already pushed the
-listed commit ID to @code{master}.
+You may also see this if the auto-build files have been deleted and this
+computer has previously already pushed the listed commit ID to
+@code{master}.
@end itemize
-
-
-@item
-@smallexample
-Git revision has not changed but checksum of test baseline has, must rebuild.
-@end smallexample
-
-This occurs when Patchy detects that the commit ID has not changed
-since the last test but it cannot locate the last
-@code{make test-baseline} (usually because it has been deleted or moved)
-and so a new @code{test-baseline} is rebuilt.
-
-@item
-@example
-Last patch for issue xxxx already tested or under testing
-by another Patchy instance, skipping.
-@end example
-
-@itemize
-
-@item
-There is another instance of Patchy running on your computer that is
-testing the same tracker issue.
-
-@item
-A previous test attempt was unsuccessful for some reason and the scripts
-were not able to tidy up after themselves (for example if you manually
-halt the testing process by killing it or closing the terminal you may
-have been running the script in).
-
-@noindent
-There is a hidden file located in the @code{$HOME} directory of the user
-running Patchy called @code{.lilypond-patchy-cache} that records the
-current patches that are being tested, have been tested and the commit
-ID of @code{remote/origin/master} since the last test. It will contain
-a line like this:
-
-@example
-[3995]
-issue105560044_120001_diff = testing
-@end example
-
-for any issue that it thinks is still in the process of being tested.
-
-@noindent
-Manually remove this entry and re-run the script.
-
-@end itemize
-
-@item
@example
test-master-lock and PID entry exist but previous Patchy
run (PID xxxxx) died, resetting test-master-lock anyway.
@end example
-@item
-A previous test attempt was unsuccessful for some reason and the scripts
-were not able to tidy up after themselves (for example if you manually
-halt the testing process by killing it or closing the terminal you may
-have been running the script in). The @code{test-master-lock} branch
-was therefore not able to be deleted cleanly however, nothing needs to
-be done the scripts will rebuild any tests it needs to.
+@noindent
+A previous attempt was unsuccessful for some reason and the scripts were
+not able to tidy up after themselves (for example if you manually halt
+the process by killing it or closing the terminal you may have been
+running the script in). The @code{test-master-lock} branch was
+therefore not able to be deleted cleanly however, nothing needs to be
+done the scripts will rebuild any tests it needs to.
-@item
@example
fatal: A branch named 'test-master-lock' already exists.
@end example
@end itemize
-@item
@example
*** FAILED STEP ***
merge from staging
This occurs when trying to run @code{lilypond-patchy-staging.py} when
another instance of either script is already running locally.
-@item
-@example
-Warning: something went wrong; omitting patch for issue 3976
-@end example
-
-@itemize
-
-@item
-The Rietveld URL as listed in the tracker is incorrect (e.g. missing or
-incorrect issue number
-
-@item
-The patch on Rietveld is too large to download
-@end itemize
-
-@end itemize
@node Administrative mailing list
Reitveld is inconvenient in some respects: it requires a google
account, and there's no way to see all patches relating to
lilypond. Should we switch to something like gerritt?
-@uref{http://code.google.com/p/lilypond/issues/detail?id=1184}
+@uref{https://sourceforge.net/p/testlilyissues/issues/1184/}
(prep: 5 hours. discuss: 15 hours)
(prep: 2 hours. discuss: 10 hours)
@item @strong{code readability}:
-"Our aim when producing source code for Lilypond in whatever
+"Our aim when producing source code for LilyPond in whatever
language is that it should be totally comprehensible to a
relatively inexperienced developer at the second reading."
@item
Discussion on
-@uref{http://code.google.com/p/lilypond/issues/detail?id=1322}
+@uref{https://sourceforge.net/p/testlilyissues/issues/1322/}
about \new vs. \context.
@item
Let users add their own items to the parser? comment 11 on:
-@uref{http://code.google.com/p/lilypond/issues/detail?id=1322}
+@uref{https://sourceforge.net/p/testlilyissues/issues/1322/}
@item
should engravers be pluralized (note_heads_engraver) or not
@item
should we allow numbers in identifier names? Issue:
-@uref{http://code.google.com/p/lilypond/issues/detail?id=1670}
+@uref{https://sourceforge.net/p/testlilyissues/issues/1670/}
@item
should we officially allow accented characters? in general, how
projects / lilypond.git / blobdiff