docserver: Adds "API scheduled for Chrome version..." text to dev and beta APIs

BUG=303975
NOTRY=true

Review URL: https://codereview.chromium.org/255473003

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@267367 0039d316-1c4b-4281-b951-d872f2087c98

10 files changed, 154 insertions, 55 deletions

diff --git a/chrome/common/extensions/docs/server2/api_data_source.py b/chrome/common/extensions/docs/server2/api_data_source.py
index 5727050..982fefb 100644
--- a/chrome/common/extensions/docs/server2/api_data_source.py
+++ b/chrome/common/extensions/docs/server2/api_data_source.py
@@ -119,7 +119,7 @@ class _JSCModel(object):
 
   def _GetChannelWarning(self):
     if not self._IsExperimental():
-      return { self._GetApiAvailability().channel: True }
+      return { self._GetApiAvailability().channel_info.channel: True }
     return None
 
   def _IsExperimental(self):
@@ -351,10 +351,12 @@ class _JSCModel(object):
     if self._IsExperimental():
       status = 'experimental'
       version = None
+      scheduled = None
     else:
       availability = self._GetApiAvailability()
-      status = availability.channel
-      version = availability.version
+      status = availability.channel_info.channel
+      version = availability.channel_info.version
+      scheduled = availability.scheduled
     return {
       'title': 'Availability',
       'content': [{
@@ -362,7 +364,8 @@ class _JSCModel(object):
           posixpath.join(PRIVATE_TEMPLATES,
                          'intro_tables',
                          '%s_message.html' % status)).Get(),
-        'version': version
+        'version': version,
+        'scheduled': scheduled
       }]
     }
 
diff --git a/chrome/common/extensions/docs/server2/api_data_source_test.py b/chrome/common/extensions/docs/server2/api_data_source_test.py
index 478226d..92cedc8 100755
--- a/chrome/common/extensions/docs/server2/api_data_source_test.py
+++ b/chrome/common/extensions/docs/server2/api_data_source_test.py
@@ -11,6 +11,7 @@ import unittest
 from api_data_source import (_JSCModel,
                              _FormatValue,
                              _GetEventByNameFromEvents)
+from availability_finder import AvailabilityInfo
 from branch_utility import ChannelInfo
 from extensions_paths import CHROME_EXTENSIONS
 from fake_host_file_system_provider import FakeHostFileSystemProvider
@@ -39,7 +40,13 @@ def _GetType(dict_, name):
 class _FakeAvailabilityFinder(object):
 
   def GetApiAvailability(self, version):
-    return ChannelInfo('stable', '396', 5)
+    return AvailabilityInfo(ChannelInfo('stable', '396', 5))
+
+
+class _FakeScheduledAvailabilityFinder(object):
+
+  def GetApiAvailability(self, version):
+    return AvailabilityInfo(ChannelInfo('beta', '1453', 27), scheduled=28)
 
 
 class _FakeTemplateCache(object):
@@ -109,12 +116,18 @@ class APIDataSourceTest(unittest.TestCase):
 
   def testGetApiAvailability(self):
     api_availabilities = {
-      'bluetooth': ChannelInfo('dev', CANNED_BRANCHES[28], 28),
-      'contextMenus': ChannelInfo('trunk', CANNED_BRANCHES['trunk'], 'trunk'),
-      'jsonStableAPI': ChannelInfo('stable', CANNED_BRANCHES[20], 20),
-      'idle': ChannelInfo('stable', CANNED_BRANCHES[5], 5),
-      'input.ime': ChannelInfo('stable', CANNED_BRANCHES[18], 18),
-      'tabs': ChannelInfo('stable', CANNED_BRANCHES[18], 18)
+      'bluetooth': AvailabilityInfo(
+          ChannelInfo('dev', CANNED_BRANCHES[28], 28)),
+      'contextMenus': AvailabilityInfo(
+          ChannelInfo('trunk', CANNED_BRANCHES['trunk'], 'trunk')),
+      'jsonStableAPI': AvailabilityInfo(
+          ChannelInfo('stable', CANNED_BRANCHES[20], 20)),
+      'idle': AvailabilityInfo(
+          ChannelInfo('stable', CANNED_BRANCHES[5], 5)),
+      'input.ime': AvailabilityInfo(
+          ChannelInfo('stable', CANNED_BRANCHES[18], 18)),
+      'tabs': AvailabilityInfo(
+          ChannelInfo('stable', CANNED_BRANCHES[18], 18))
     }
     for api_name, availability in api_availabilities.iteritems():
       model = _JSCModel(self._avail_api_models.GetModel(api_name).Get(),
@@ -142,7 +155,8 @@ class APIDataSourceTest(unittest.TestCase):
         'content': [
           { 'partial': 'handlebar chrome/common/extensions/docs/' +
                        'templates/private/intro_tables/stable_message.html',
-            'version': 5
+            'version': 5,
+            'scheduled': None
           }
         ]
       },
@@ -171,6 +185,25 @@ class APIDataSourceTest(unittest.TestCase):
     ]
     self.assertEquals(model._GetIntroTableList(), expected_list)
 
+    # Tests the same data with a scheduled availability.
+    model = _JSCModel(self._api_models.GetModel('tester').Get(),
+                      _FakeScheduledAvailabilityFinder(),
+                      self._json_cache,
+                      _FakeTemplateCache(),
+                      self._features_bundle,
+                      None)
+    expected_list[1] = {
+      'title': 'Availability',
+      'content': [
+        { 'partial': 'handlebar chrome/common/extensions/docs/' +
+                     'templates/private/intro_tables/beta_message.html',
+          'version': 27,
+          'scheduled': 28
+        }
+      ]
+    }
+    self.assertEquals(model._GetIntroTableList(), expected_list)
+
   def testGetEventByNameFromEvents(self):
     events = {}
     # Missing 'types' completely.
diff --git a/chrome/common/extensions/docs/server2/api_list_data_source.py b/chrome/common/extensions/docs/server2/api_list_data_source.py
index 04c4b35..abbf397 100644
--- a/chrome/common/extensions/docs/server2/api_list_data_source.py
+++ b/chrome/common/extensions/docs/server2/api_list_data_source.py
@@ -33,7 +33,7 @@ class APIListDataSource(DataSource):
 
   def _GenerateAPIDict(self):
     def get_channel_info(api_name):
-      return self._availability_finder.GetApiAvailability(api_name)
+      return self._availability_finder.GetApiAvailability(api_name).channel_info
 
     def get_api_platform(api_name):
       feature = self._features_bundle.GetAPIFeatures().Get()[api_name]
diff --git a/chrome/common/extensions/docs/server2/app.yaml b/chrome/common/extensions/docs/server2/app.yaml
index d7d1ca3..d6a5ed2 100644
--- a/chrome/common/extensions/docs/server2/app.yaml
+++ b/chrome/common/extensions/docs/server2/app.yaml
@@ -1,5 +1,5 @@
 application: chrome-apps-doc
-version: 3-21-0
+version: 3-22-0
 runtime: python27
 api_version: 1
 threadsafe: false
diff --git a/chrome/common/extensions/docs/server2/availability_finder.py b/chrome/common/extensions/docs/server2/availability_finder.py
index 31564d1..86e2de2 100644
--- a/chrome/common/extensions/docs/server2/availability_finder.py
+++ b/chrome/common/extensions/docs/server2/availability_finder.py
@@ -6,7 +6,7 @@ from collections import Mapping
 import posixpath
 
 from api_schema_graph import APISchemaGraph
-from branch_utility import BranchUtility
+from branch_utility import BranchUtility, ChannelInfo
 from extensions_paths import API_PATHS, JSON_TEMPLATES
 from features_bundle import FeaturesBundle
 import features_utility
@@ -36,6 +36,30 @@ def _GetChannelFromFeatures(api_name, features):
   return feature.get('channel') if feature else None
 
 
+class AvailabilityInfo(object):
+  '''Represents availability data for an API. |scheduled| is a version number
+  specifying when dev and beta APIs will become stable, or None if that data
+  is unknown.
+  '''
+  def __init__(self, channel_info, scheduled=None):
+    assert isinstance(channel_info, ChannelInfo)
+    assert isinstance(scheduled, int) or scheduled is None
+    self.channel_info = channel_info
+    self.scheduled = scheduled
+
+  def __eq__(self, other):
+    return self.__dict__ == other.__dict__
+
+  def __ne__(self, other):
+    return not (self == other)
+
+  def __repr__(self):
+    return '%s%s' % (type(self).__name__, repr(self.__dict__))
+
+  def __str__(self):
+    return repr(self)
+
+
 class AvailabilityFinder(object):
   '''Generates availability information for APIs by looking at API schemas and
   _features files over multiple release versions of Chrome.
@@ -67,9 +91,10 @@ class AvailabilityFinder(object):
     if api_info is None:
       return None
     if api_info['channel'] == 'stable':
-      return self._branch_utility.GetStableChannelInfo(api_info['version'])
-    else:
-      return self._branch_utility.GetChannelInfo(api_info['channel'])
+      return AvailabilityInfo(
+          self._branch_utility.GetStableChannelInfo(api_info['version']))
+    return AvailabilityInfo(
+        self._branch_utility.GetChannelInfo(api_info['channel']))
 
   def _GetApiSchemaFilename(self, api_name, file_system, version):
     '''Gets the name of the file which may contain the schema for |api_name| in
@@ -208,6 +233,21 @@ class AvailabilityFinder(object):
                                           file_system,
                                           channel_info)
 
+  def _FindScheduled(self, api_name):
+    '''Determines the earliest version of Chrome where the API is stable.
+    Unlike the code in GetApiAvailability, this checks if the API is stable
+    even when Chrome is in dev or beta, which shows that the API is scheduled
+    to be stable in that verison of Chrome.
+    '''
+    def check_scheduled(file_system, channel_info):
+      return self._CheckStableAvailability(
+          api_name, file_system, channel_info.version)
+
+    stable_channel = self._file_system_iterator.Descending(
+        self._branch_utility.GetChannelInfo('dev'), check_scheduled)
+
+    return stable_channel.version if stable_channel else None
+
   def GetApiAvailability(self, api_name):
     '''Performs a search for an API's top-level availability by using a
     HostFileSystemIterator instance to traverse multiple version of the
@@ -226,12 +266,21 @@ class AvailabilityFinder(object):
     def check_api_availability(file_system, channel_info):
       return self._CheckApiAvailability(api_name, file_system, channel_info)
 
-    availability = self._file_system_iterator.Descending(
+    channel_info = self._file_system_iterator.Descending(
         self._branch_utility.GetChannelInfo('dev'),
         check_api_availability)
-    if availability is None:
+    if channel_info is None:
       # The API wasn't available on 'dev', so it must be a 'trunk'-only API.
-      availability = self._branch_utility.GetChannelInfo('trunk')
+      channel_info = self._branch_utility.GetChannelInfo('trunk')
+
+    # If the API is not stable, check when it will be scheduled to be stable.
+    if channel_info.channel == 'stable':
+      scheduled = None
+    else:
+      scheduled = self._FindScheduled(api_name)
+
+    availability = AvailabilityInfo(channel_info, scheduled=scheduled)
+
     self._top_level_object_store.Set(api_name, availability)
     return availability
 
@@ -284,8 +333,9 @@ class AvailabilityFinder(object):
       # version and trunk.
       return version_stat != trunk_stat
 
-    self._file_system_iterator.Ascending(self.GetApiAvailability(api_name),
-                                         update_availability_graph)
+    self._file_system_iterator.Ascending(
+        self.GetApiAvailability(api_name).channel_info,
+        update_availability_graph)
 
     self._node_level_object_store.Set(api_name, availability_graph)
     return availability_graph
diff --git a/chrome/common/extensions/docs/server2/availability_finder_test.py b/chrome/common/extensions/docs/server2/availability_finder_test.py
index 22d050b..330fb47 100755
--- a/chrome/common/extensions/docs/server2/availability_finder_test.py
+++ b/chrome/common/extensions/docs/server2/availability_finder_test.py
@@ -7,7 +7,7 @@ import sys
 import unittest
 
 import api_schema_graph
-from availability_finder import AvailabilityFinder
+from availability_finder import AvailabilityFinder, AvailabilityInfo
 from branch_utility import BranchUtility, ChannelInfo
 from compiled_file_system import CompiledFileSystem
 from fake_host_file_system_provider import FakeHostFileSystemProvider
@@ -97,120 +97,122 @@ class AvailabilityFinderTest(unittest.TestCase):
 
     # Testing APIs with predetermined availability.
     self.assertEqual(
-        ChannelInfo('trunk', 'trunk', 'trunk'),
+        AvailabilityInfo(ChannelInfo('trunk', 'trunk', 'trunk')),
         self._avail_finder.GetApiAvailability('jsonTrunkAPI'))
     self.assertEqual(
-        ChannelInfo('dev', CANNED_BRANCHES[28], 28),
+        AvailabilityInfo(ChannelInfo('dev', CANNED_BRANCHES[28], 28)),
         self._avail_finder.GetApiAvailability('jsonDevAPI'))
     self.assertEqual(
-        ChannelInfo('beta', CANNED_BRANCHES[27], 27),
+        AvailabilityInfo(ChannelInfo('beta', CANNED_BRANCHES[27], 27)),
         self._avail_finder.GetApiAvailability('jsonBetaAPI'))
     self.assertEqual(
-        ChannelInfo('stable', CANNED_BRANCHES[20], 20),
+        AvailabilityInfo(ChannelInfo('stable', CANNED_BRANCHES[20], 20)),
         self._avail_finder.GetApiAvailability('jsonStableAPI'))
 
     # Testing a whitelisted API.
     self.assertEquals(
-        ChannelInfo('beta', CANNED_BRANCHES[27], 27),
+        AvailabilityInfo(ChannelInfo('beta', CANNED_BRANCHES[27], 27)),
         self._avail_finder.GetApiAvailability('declarativeWebRequest'))
 
     # Testing APIs found only by checking file system existence.
     self.assertEquals(
-        ChannelInfo('stable', CANNED_BRANCHES[23], 23),
+        AvailabilityInfo(ChannelInfo('stable', CANNED_BRANCHES[23], 23)),
         self._avail_finder.GetApiAvailability('windows'))
     self.assertEquals(
-        ChannelInfo('stable', CANNED_BRANCHES[18], 18),
+        AvailabilityInfo(ChannelInfo('stable', CANNED_BRANCHES[18], 18)),
         self._avail_finder.GetApiAvailability('tabs'))
     self.assertEquals(
-        ChannelInfo('stable', CANNED_BRANCHES[18], 18),
+        AvailabilityInfo(ChannelInfo('stable', CANNED_BRANCHES[18], 18)),
         self._avail_finder.GetApiAvailability('input.ime'))
 
     # Testing API channel existence for _api_features.json.
     # Listed as 'dev' on |beta|, 'dev' on |dev|.
     self.assertEquals(
-        ChannelInfo('dev', CANNED_BRANCHES[28], 28),
+        AvailabilityInfo(ChannelInfo('dev', CANNED_BRANCHES[28], 28)),
         self._avail_finder.GetApiAvailability('systemInfo.stuff'))
     # Listed as 'stable' on |beta|.
     self.assertEquals(
+        AvailabilityInfo(
         ChannelInfo('beta', CANNED_BRANCHES[27], 27),
+        scheduled=28),
         self._avail_finder.GetApiAvailability('systemInfo.cpu'))
 
     # Testing API channel existence for _manifest_features.json.
     # Listed as 'trunk' on all channels.
     self.assertEquals(
-        ChannelInfo('trunk', 'trunk', 'trunk'),
+        AvailabilityInfo(ChannelInfo('trunk', 'trunk', 'trunk')),
         self._avail_finder.GetApiAvailability('sync'))
     # No records of API until |trunk|.
     self.assertEquals(
-        ChannelInfo('trunk', 'trunk', 'trunk'),
+        AvailabilityInfo(ChannelInfo('trunk', 'trunk', 'trunk')),
         self._avail_finder.GetApiAvailability('history'))
     # Listed as 'dev' on |dev|.
     self.assertEquals(
-        ChannelInfo('dev', CANNED_BRANCHES[28], 28),
+        AvailabilityInfo(ChannelInfo('dev', CANNED_BRANCHES[28], 28)),
         self._avail_finder.GetApiAvailability('storage'))
     # Stable in _manifest_features and into pre-18 versions.
     self.assertEquals(
-        ChannelInfo('stable', CANNED_BRANCHES[8], 8),
+        AvailabilityInfo(ChannelInfo('stable', CANNED_BRANCHES[8], 8)),
         self._avail_finder.GetApiAvailability('pageAction'))
 
     # Testing API channel existence for _permission_features.json.
     # Listed as 'beta' on |trunk|.
     self.assertEquals(
-        ChannelInfo('trunk', 'trunk', 'trunk'),
+        AvailabilityInfo(ChannelInfo('trunk', 'trunk', 'trunk')),
         self._avail_finder.GetApiAvailability('falseBetaAPI'))
     # Listed as 'trunk' on |trunk|.
     self.assertEquals(
-        ChannelInfo('trunk', 'trunk', 'trunk'),
+        AvailabilityInfo(ChannelInfo('trunk', 'trunk', 'trunk')),
         self._avail_finder.GetApiAvailability('trunkAPI'))
     # Listed as 'trunk' on all development channels.
     self.assertEquals(
-        ChannelInfo('trunk', 'trunk', 'trunk'),
+        AvailabilityInfo(ChannelInfo('trunk', 'trunk', 'trunk')),
         self._avail_finder.GetApiAvailability('declarativeContent'))
     # Listed as 'dev' on all development channels.
     self.assertEquals(
-        ChannelInfo('dev', CANNED_BRANCHES[28], 28),
+        AvailabilityInfo(ChannelInfo('dev', CANNED_BRANCHES[28], 28)),
         self._avail_finder.GetApiAvailability('bluetooth'))
     # Listed as 'dev' on |dev|.
     self.assertEquals(
-        ChannelInfo('dev', CANNED_BRANCHES[28], 28),
+        AvailabilityInfo(ChannelInfo('dev', CANNED_BRANCHES[28], 28)),
         self._avail_finder.GetApiAvailability('cookies'))
     # Treated as 'stable' APIs.
     self.assertEquals(
-        ChannelInfo('stable', CANNED_BRANCHES[24], 24),
+        AvailabilityInfo(ChannelInfo('stable', CANNED_BRANCHES[24], 24)),
         self._avail_finder.GetApiAvailability('alarms'))
     self.assertEquals(
-        ChannelInfo('stable', CANNED_BRANCHES[21], 21),
+        AvailabilityInfo(ChannelInfo('stable', CANNED_BRANCHES[21], 21)),
         self._avail_finder.GetApiAvailability('bookmarks'))
 
     # Testing older API existence using extension_api.json.
     self.assertEquals(
-        ChannelInfo('stable', CANNED_BRANCHES[6], 6),
+        AvailabilityInfo(ChannelInfo('stable', CANNED_BRANCHES[6], 6)),
         self._avail_finder.GetApiAvailability('menus'))
     self.assertEquals(
-        ChannelInfo('stable', CANNED_BRANCHES[5], 5),
+        AvailabilityInfo(ChannelInfo('stable', CANNED_BRANCHES[5], 5)),
         self._avail_finder.GetApiAvailability('idle'))
 
     # Switches between _features.json files across branches.
     # Listed as 'trunk' on all channels, in _api, _permission, or _manifest.
     self.assertEquals(
-        ChannelInfo('trunk', 'trunk', 'trunk'),
+        AvailabilityInfo(ChannelInfo('trunk', 'trunk', 'trunk')),
         self._avail_finder.GetApiAvailability('contextMenus'))
     # Moves between _permission and _manifest as file system is traversed.
     self.assertEquals(
-        ChannelInfo('stable', CANNED_BRANCHES[23], 23),
+        AvailabilityInfo(ChannelInfo('stable', CANNED_BRANCHES[23], 23)),
         self._avail_finder.GetApiAvailability('systemInfo.display'))
     self.assertEquals(
-        ChannelInfo('stable', CANNED_BRANCHES[17], 17),
+        AvailabilityInfo(ChannelInfo('stable', CANNED_BRANCHES[17], 17)),
         self._avail_finder.GetApiAvailability('webRequest'))
 
     # Mid-upgrade cases:
     # Listed as 'dev' on |beta| and 'beta' on |dev|.
     self.assertEquals(
-        ChannelInfo('dev', CANNED_BRANCHES[28], 28),
+        AvailabilityInfo(ChannelInfo('dev', CANNED_BRANCHES[28], 28)),
         self._avail_finder.GetApiAvailability('notifications'))
     # Listed as 'beta' on |stable|, 'dev' on |beta| ... until |stable| on trunk.
     self.assertEquals(
-        ChannelInfo('trunk', 'trunk', 'trunk'),
+        AvailabilityInfo(ChannelInfo('trunk', 'trunk', 'trunk')),
         self._avail_finder.GetApiAvailability('events'))
 
   def testGetApiNodeAvailability(self):
diff --git a/chrome/common/extensions/docs/server2/cron.yaml b/chrome/common/extensions/docs/server2/cron.yaml
index 6db2fb7..7ad3e49 100644
--- a/chrome/common/extensions/docs/server2/cron.yaml
+++ b/chrome/common/extensions/docs/server2/cron.yaml
@@ -2,4 +2,4 @@ cron:
 - description: Repopulates all cached data.
   url: /_cron
   schedule: every 5 minutes
-  target: 3-21-0
+  target: 3-22-0
diff --git a/chrome/common/extensions/docs/server2/whats_new_data_source.py b/chrome/common/extensions/docs/server2/whats_new_data_source.py
index 7d67a20..6055a74 100644
--- a/chrome/common/extensions/docs/server2/whats_new_data_source.py
+++ b/chrome/common/extensions/docs/server2/whats_new_data_source.py
@@ -36,7 +36,8 @@ class WhatsNewDataSource(DataSource):
     version = None
     category = self._api_categorizer.GetCategory(platform, api_name)
     if category == 'chrome':
-      channel_info = self._availability_finder.GetApiAvailability(api_name)
+      channel_info = self._availability_finder.GetApiAvailability(
+          api_name).channel_info
       channel = channel_info.channel
       if channel == 'stable':
         version = channel_info.version
diff --git a/chrome/common/extensions/docs/templates/private/intro_tables/beta_message.html b/chrome/common/extensions/docs/templates/private/intro_tables/beta_message.html
index 413911f..3c6c48e 100644
--- a/chrome/common/extensions/docs/templates/private/intro_tables/beta_message.html
+++ b/chrome/common/extensions/docs/templates/private/intro_tables/beta_message.html
@@ -1,2 +1,7 @@
 <a href="https://www.google.com/landing/chrome/beta/">Beta</a> and 
-<a href="http://www.chromium.org/getting-involved/dev-channel">dev</a> channels only.
+<a href="http://www.chromium.org/getting-involved/dev-channel">dev</a> channels 
+{{?content.scheduled}}
+(scheduled for Chrome {{content.scheduled}}).
+{{:content.scheduled}}
+only.
+{{/content.scheduled}}
diff --git a/chrome/common/extensions/docs/templates/private/intro_tables/dev_message.html b/chrome/common/extensions/docs/templates/private/intro_tables/dev_message.html
index 1ecf834..f3479e1 100644
--- a/chrome/common/extensions/docs/templates/private/intro_tables/dev_message.html
+++ b/chrome/common/extensions/docs/templates/private/intro_tables/dev_message.html
@@ -1 +1,6 @@
-<a href="http://www.chromium.org/getting-involved/dev-channel">Dev</a> channel only.
+<a href="http://www.chromium.org/getting-involved/dev-channel">Dev</a> channel 
+{{?content.scheduled}}
+(scheduled for Chrome {{content.scheduled}}).
+{{:content.scheduled}}
+only.
+{{/content.scheduled}}