Presubmit: Tweak the help text for making API changes

PRESUBMIT.py

 # Copyright (c) 2012 The WebRTC project authors. All Rights Reserved.
 #
 # Use of this source code is governed by a BSD-style license
 # that can be found in the LICENSE file in the root of the source
 # tree. An additional intellectual property rights grant can be found
 # in the file PATENTS.  All contributing project authors may
 # be found in the AUTHORS file in the root of the source tree.
 
 import json
 import os
@@ skipping 76 matching lines @@
     if not os.path.isdir(path):
       non_existing_paths.append(path)
   if non_existing_paths:
     return [output_api.PresubmitError(
         'Directories to native API headers have changed which has made the '
         'list in PRESUBMIT.py outdated.\nPlease update it to the current '
         'location of our native APIs.',
         non_existing_paths)]
   return []
 
+api_change_msg = """
+You seem to be changing native API header files. Please make sure that you:
+  1. Make compatible changes that don't break existing clients.
+  2. Mark the old stuff as deprecated.
+  3. Create a timeline and plan for when the deprecated stuff will be
+     removed. (The amount of time we give users to change their code
+     should be informed by how much work it is for them. If they just
+     need to replace one name with another or something equally
+     simple, 1-2 weeks might be good; if they need to do serious work,
+     up to 3 months may be called for.)
+  4. Update/inform existing downstream code owners to stop using the
+     deprecated stuff. (Send announcements to
+     discuss-webrtc@googlegroups.com and webrtc-users@google.com.)
+  5. Remove the deprecated stuff, once the agreed-upon amount of time
+     has passed.
+Related files:
+""".strip()

[kjellander_webrtc, 2016/04/07 12:44:03]

Remove the strip, as it will remove the last newline, which makes the output
look worse IMO.

[kwiberg-webrtc, 2016/04/07 12:52:24]

Gladly. I did it this way because that's what the old code did.

[kjellander_webrtc, 2016/04/07 13:04:13]

Hmm, you're right the old code doesn't have a newline. Feel free to ignore my
comment then. I didn't try it myself so I guess the PresubmitNotifyResult
function possibly ends with a newline by itself before listing the files.

[kwiberg-webrtc, 2016/04/07 13:06:47]

I tried both variants, and slightly prefer the non-stripping one. (Note that
without the strip, this CL adds a newline both before and after the text. This
makes it easier to read, IMO.)

 
 def _CheckNativeApiHeaderChanges(input_api, output_api):
   """Checks to remind proper changing of native APIs."""
   files = []
   for f in input_api.AffectedSourceFiles(input_api.FilterSourceFile):
     if f.LocalPath().endswith('.h'):
       for path in NATIVE_API_DIRS:
         if os.path.dirname(f.LocalPath()) == path:
           files.append(f)
 
   if files:
-    return [output_api.PresubmitNotifyResult(
-        'You seem to be changing native API header files. Please make sure '
-        'you:\n'
-        '  1. Make compatible changes that don\'t break existing clients.\n'
-        '  2. Mark the old APIs as deprecated.\n'
-        '  3. Create a timeline and plan for when the deprecated method will '
-        'be removed (preferably 3 months or so).\n'
-        '  4. Update/inform existing downstream code owners to stop using the '
-        'deprecated APIs: \n'
-        'send announcement to discuss-webrtc@googlegroups.com and '
-        'webrtc-users@google.com.\n'
-        '  5. (after ~3 months) remove the deprecated API.\n'
-        'Related files:',
-        files)]
+    return [output_api.PresubmitNotifyResult(api_change_msg, files)]
   return []
 
 
 def _CheckNoIOStreamInHeaders(input_api, output_api):
   """Checks to make sure no .h files include <iostream>."""
   files = []
   pattern = input_api.re.compile(r'^#include\s*<iostream>',
                                  input_api.re.MULTILINE)
   for f in input_api.AffectedSourceFiles(input_api.FilterSourceFile):
     if not f.LocalPath().endswith('.h'):
@@ skipping 378 matching lines @@
     for builder in masters[master]:
       if 'presubmit' in builder:
         # Do not trigger presubmit builders, since they're likely to fail
         # (e.g. OWNERS checks before finished code review), and we're running
         # local presubmit anyway.
         pass
       else:
         try_config[master][builder] = ['defaulttests']
 
   return try_config