rebaseline_server: deprecate --expectations-dir option in advance of git transition

gm/rebaseline_server/server.py

 #!/usr/bin/python
 
 """
 Copyright 2013 Google Inc.
 
 Use of this source code is governed by a BSD-style license that can be
 found in the LICENSE file.
 
 HTTP server for our HTML rebaseline viewer.
 """
@@ skipping 90 matching lines @@
 
   def __init__(self,
                actuals_dir=DEFAULT_ACTUALS_DIR,
                expectations_dir=DEFAULT_EXPECTATIONS_DIR,
                port=DEFAULT_PORT, export=False, editable=True,
                reload_seconds=0):
     """
     Args:
       actuals_dir: directory under which we will check out the latest actual
                    GM results
-      expectations_dir: directory under which to find GM expectations (they
-                        must already be in that directory)
+      expectations_dir: DEPRECATED: directory under which to find
+                        GM expectations (they must already be in that directory)
       port: which TCP port to listen on for HTTP requests
       export: whether to allow HTTP clients on other hosts to access this server
       editable: whether HTTP clients are allowed to submit new baselines
       reload_seconds: polling interval with which to check for new results;
                       if 0, don't check for new results at all
     """
     self._actuals_dir = actuals_dir
     self._expectations_dir = expectations_dir
     self._port = port
     self._export = export
     self._editable = editable
     self._reload_seconds = reload_seconds
     self._actuals_repo = _create_svn_checkout(
         dir_path=actuals_dir, repo_url=ACTUALS_SVN_REPO)
 
     # We only update the expectations dir if the server was run with a
     # nonzero --reload argument; otherwise, we expect the user to maintain
     # her own expectations as she sees fit.
     #
     # TODO(epoger): Use git instead of svn to check out expectations, since
     # the Skia repo is moving to git.
     if reload_seconds:
       self._expectations_repo = _create_svn_checkout(

[epoger, 2013/11/21 17:08:37]

see comments below

           dir_path=expectations_dir, repo_url=EXPECTATIONS_SVN_REPO)
     else:
       self._expectations_repo = None
 
   def is_exported(self):
     """ Returns true iff HTTP clients on other hosts are allowed to access
     this server. """
     return self._export
 
   def is_editable(self):
@@ skipping 281 matching lines @@
 def main():
   logging.basicConfig(level=logging.INFO)
   parser = argparse.ArgumentParser()
   parser.add_argument('--actuals-dir',
                     help=('Directory into which we will check out the latest '
                           'actual GM results. If this directory does not '
                           'exist, it will be created. Defaults to %(default)s'),
                     default=DEFAULT_ACTUALS_DIR)
   parser.add_argument('--editable', action='store_true',
                       help=('Allow HTTP clients to submit new baselines.'))
-  parser.add_argument('--expectations-dir',
-                    help=('Directory under which to find GM expectations; '
+  # Deprecated the --expectations-dir option, because once our GM expectations
+  # are maintained within git we will no longer be able to check out and update
+  # them in isolation (in SVN you can update a single directory subtree within
+  # a checkout, but you cannot do that with git).
+  #
+  # In a git world, we will force the user to refer to expectations
+  # within the same checkout as this tool (at the relative path
+  # ../../expectations/gm ).  If they specify the --reload option, we will
+  # periodically run "git pull" on the entire Skia checkout, which will update
+  # the GM expectations along with everything else (such as this script).
+  #
+  # We can still allow --actuals-dir to be specified, though, because the
+  # actual results will continue to be maintained in the skia-autogen
+  # SVN repository.
+  parser.add_argument('--deprecated-expectations-dir',
+                    help=('DEPRECATED due to our transition from SVN to git '
+                          '(formerly known as --expectations-dir).  '
+                          'If you still need this option, contact '
+                          'epoger@google.com as soon as possible.  WAS: '
+                          'Directory under which to find GM expectations; '

[epoger, 2013/11/21 17:08:37]

Alternatively, we could allow the user to specify a path to git checkout root
containing expectations (a directory within which expectations can be found at
"expectations/gm").  By default, the path to git checkout root would be "../..",
and thus we would use the expectations within the same checkout as this script.

Two problems with that:

1. In order for _create_svn_checkout() at line 135 to check out expectations
into that other directory, it would need to download the entire history of the
entire Skia git repo.

2. The meaning of the option would have to change.  (The caller would have to
specify the path to git checkout root, not "expectations/gm" within the
checkout.)

                           'defaults to %(default)s'),
                     default=DEFAULT_EXPECTATIONS_DIR)
   parser.add_argument('--export', action='store_true',
                       help=('Instead of only allowing access from HTTP clients '
                             'on localhost, allow HTTP clients on other hosts '
                             'to access this server.  WARNING: doing so will '
                             'allow users on other hosts to modify your '
                             'GM expectations, if combined with --editable.'))
   parser.add_argument('--port', type=int,
                       help=('Which TCP port to listen on for HTTP requests; '
                             'defaults to %(default)s'),
                       default=DEFAULT_PORT)
   parser.add_argument('--reload', type=int,
                       help=('How often (a period in seconds) to update the '
-                            'results.  If specified, both EXPECTATIONS_DIR and '
+                            'results.  If specified, both '
+                            'DEPRECATED_EXPECTATIONS_DIR and '
                             'ACTUAL_DIR will be updated.  '
                             'By default, we do not reload at all, and you '
                             'must restart the server to pick up new data.'),
                       default=0)
   args = parser.parse_args()
   global _SERVER
   _SERVER = Server(actuals_dir=args.actuals_dir,
-                   expectations_dir=args.expectations_dir,
+                   expectations_dir=args.deprecated_expectations_dir,
                    port=args.port, export=args.export, editable=args.editable,
                    reload_seconds=args.reload)
   _SERVER.run()
 
 if __name__ == '__main__':
   main()