define description overrides by version, like examples

docs/_descriptions/search.asciidoc

@@ -1,4 +1,4 @@
 Return documents matching a query, aggregations/facets, highlighted snippets, suggestions, and more. Write your queries as either http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-uri-request.html[simple query strings] in the `q` parameter, or by specifying a http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-body.html[full request definition] using the http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html[Elasticsearch Query DSL] in the `body` parameter.
 
-TIP: https://github.com/danpaz/bodybuilder[bodybuilder], https://github.com/holidayextras/esq[esq], https://github.com/sudo-suhas/elastic-builder[elastic-builder] or https://github.com/fullscale/elastic.js[elastic.js] can be used to make building query bodies easier.
+TIP: https://github.com/danpaz/bodybuilder[bodybuilder] and https://github.com/sudo-suhas/elastic-builder[elastic-builder] can be used to make building query bodies easier.
 

docs/_descriptions/search_0.90.asciidoc

@@ -0,0 +1,2 @@
+Return documents matching a query, aggregations/facets, highlighted snippets, suggestions, and more. Write your queries as either http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-uri-request.html[simple query strings] in the `q` parameter, or by specifying a http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-body.html[full request definition] using the http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html[Elasticsearch Query DSL] in the `body` parameter.
+

docs/_descriptions/search_1.x.asciidoc

@@ -0,0 +1,4 @@
+Return documents matching a query, aggregations/facets, highlighted snippets, suggestions, and more. Write your queries as either http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-uri-request.html[simple query strings] in the `q` parameter, or by specifying a http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-body.html[full request definition] using the http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html[Elasticsearch Query DSL] in the `body` parameter.
+
+TIP: https://github.com/danpaz/bodybuilder[bodybuilder], https://github.com/holidayextras/esq[esq], and https://github.com/fullscale/elastic.js[elastic.js] can be used to make building query bodies easier.
+

docs/_descriptions/search_2.x.asciidoc

@@ -0,0 +1,4 @@
+Return documents matching a query, aggregations/facets, highlighted snippets, suggestions, and more. Write your queries as either http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-uri-request.html[simple query strings] in the `q` parameter, or by specifying a http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-body.html[full request definition] using the http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html[Elasticsearch Query DSL] in the `body` parameter.
+
+TIP: https://github.com/danpaz/bodybuilder[bodybuilder], https://github.com/sudo-suhas/elastic-builder[elastic-builder], and https://github.com/holidayextras/esq[esq] can be used to make building query bodies easier.
+

docs/_examples/scroll.asciidoc

@@ -6,19 +6,17 @@ var allTitles = [];
 // first we do a search, and specify a scroll timeout
 client.search({
   index: 'myindex',
-  // Set to 30 seconds because we are calling right back
-  scroll: '30s',
-  search_type: 'scan',
-  fields: ['title'],
+  scroll: '30s', // keep the search results "scrollable" for 30 seconds
+  source: ['title'], // filter the source to only include the title field
   q: 'title:test'
 }, function getMoreUntilDone(error, response) {
   // collect the title from each response
   response.hits.hits.forEach(function (hit) {
-    allTitles.push(hit.fields.title);
+    allTitles.push(hit._source.title);
   });
 
-  if (response.hits.total !== allTitles.length) {
-    // now we can call scroll over and over
+  if (response.hits.total > allTitles.length) {
+    // ask elasticsearch for the next set of hits from this search
     client.scroll({
       scrollId: response._scroll_id,
       scroll: '30s'

docs/_examples/scroll_<5.0.asciidoc

@@ -6,17 +6,19 @@ var allTitles = [];
 // first we do a search, and specify a scroll timeout
 client.search({
   index: 'myindex',
-  scroll: '30s', // keep the search results "scrollable" for 30 seconds
-  source: ['title'], // filter the source to only include the title field
+  // Set to 30 seconds because we are calling right back
+  scroll: '30s',
+  search_type: 'scan',
+  fields: ['title'],
   q: 'title:test'
 }, function getMoreUntilDone(error, response) {
   // collect the title from each response
   response.hits.hits.forEach(function (hit) {
-    allTitles.push(hit._source.title);
+    allTitles.push(hit.fields.title);
   });
 
-  if (response.hits.total > allTitles.length) {
-    // ask elasticsearch for the next set of hits from this search
+  if (response.hits.total !== allTitles.length) {
+    // now we can call scroll over and over
     client.scroll({
       scrollId: response._scroll_id,
       scroll: '30s'

docs/api_methods.asciidoc

@@ -1663,7 +1663,7 @@ client.search([params, [callback]])
 
 Return documents matching a query, aggregations/facets, highlighted snippets, suggestions, and more. Write your queries as either http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-uri-request.html[simple query strings] in the `q` parameter, or by specifying a http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-body.html[full request definition] using the http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html[Elasticsearch Query DSL] in the `body` parameter.
 
-TIP: https://github.com/danpaz/bodybuilder[bodybuilder], https://github.com/holidayextras/esq[esq], or https://github.com/sudo-suhas/elastic-builder[elastic-builder] can be used to make building query bodies easier.
+TIP: https://github.com/danpaz/bodybuilder[bodybuilder] and https://github.com/sudo-suhas/elastic-builder[elastic-builder] can be used to make building query bodies easier.
 
 
 

docs/api_methods_0_90.asciidoc

@@ -1132,7 +1132,6 @@ client.search({
 ---------
 
 
-
 *Params*
 
 [horizontal]
@@ -1155,7 +1154,7 @@ client.search([params, [callback]])
 
 Return documents matching a query, aggregations/facets, highlighted snippets, suggestions, and more. Write your queries as either http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-uri-request.html[simple query strings] in the `q` parameter, or by specifying a http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-body.html[full request definition] using the http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html[Elasticsearch Query DSL] in the `body` parameter.
 
-TIP: https://github.com/fullscale/elastic.js[elastic.js], https://github.com/holidayextras/esq[esq], or https://github.com/danpaz/bodybuilder[bodybuilder] can be used to make building query bodies easier.
+TIP: https://github.com/danpaz/bodybuilder[bodybuilder], https://github.com/holidayextras/esq[esq], and https://github.com/fullscale/elastic.js[elastic.js] can be used to make building query bodies easier.
 
 
 

docs/api_methods_1_7.asciidoc

@@ -1625,7 +1625,6 @@ client.search({
 ---------
 
 
-
 *Params*
 
 [horizontal]
@@ -1648,7 +1647,7 @@ client.search([params, [callback]])
 
 Return documents matching a query, aggregations/facets, highlighted snippets, suggestions, and more. Write your queries as either http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-uri-request.html[simple query strings] in the `q` parameter, or by specifying a http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-body.html[full request definition] using the http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html[Elasticsearch Query DSL] in the `body` parameter.
 
-TIP: https://github.com/fullscale/elastic.js[elastic.js], https://github.com/holidayextras/esq[esq], or https://github.com/danpaz/bodybuilder[bodybuilder] can be used to make building query bodies easier.
+TIP: https://github.com/danpaz/bodybuilder[bodybuilder], https://github.com/holidayextras/esq[esq], and https://github.com/fullscale/elastic.js[elastic.js] can be used to make building query bodies easier.
 
 
 

docs/api_methods_2_4.asciidoc

@@ -1537,7 +1537,6 @@ client.search({
 ---------
 
 
-
 *Params*
 
 [horizontal]
@@ -1560,7 +1559,7 @@ client.search([params, [callback]])
 
 Return documents matching a query, aggregations/facets, highlighted snippets, suggestions, and more. Write your queries as either http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-uri-request.html[simple query strings] in the `q` parameter, or by specifying a http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-body.html[full request definition] using the http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html[Elasticsearch Query DSL] in the `body` parameter.
 
-TIP: https://github.com/fullscale/elastic.js[elastic.js], https://github.com/holidayextras/esq[esq], https://github.com/danpaz/bodybuilder[bodybuilder], or https://github.com/sudo-suhas/elastic-builder[elastic-builder] can be used to make building query bodies easier.
+TIP: https://github.com/danpaz/bodybuilder[bodybuilder], https://github.com/sudo-suhas/elastic-builder[elastic-builder], and https://github.com/holidayextras/esq[esq] can be used to make building query bodies easier.
 
 
 

docs/api_methods_5_0.asciidoc

@@ -1665,7 +1665,7 @@ client.search([params, [callback]])
 
 Return documents matching a query, aggregations/facets, highlighted snippets, suggestions, and more. Write your queries as either http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-uri-request.html[simple query strings] in the `q` parameter, or by specifying a http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-body.html[full request definition] using the http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html[Elasticsearch Query DSL] in the `body` parameter.
 
-TIP: https://github.com/danpaz/bodybuilder[bodybuilder], https://github.com/holidayextras/esq[esq], or https://github.com/sudo-suhas/elastic-builder[elastic-builder] can be used to make building query bodies easier.
+TIP: https://github.com/danpaz/bodybuilder[bodybuilder] and https://github.com/sudo-suhas/elastic-builder[elastic-builder] can be used to make building query bodies easier.
 
 
 

docs/api_methods_5_1.asciidoc

@@ -1663,7 +1663,7 @@ client.search([params, [callback]])
 
 Return documents matching a query, aggregations/facets, highlighted snippets, suggestions, and more. Write your queries as either http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-uri-request.html[simple query strings] in the `q` parameter, or by specifying a http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-body.html[full request definition] using the http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html[Elasticsearch Query DSL] in the `body` parameter.
 
-TIP: https://github.com/danpaz/bodybuilder[bodybuilder], https://github.com/holidayextras/esq[esq], or https://github.com/sudo-suhas/elastic-builder[elastic-builder] can be used to make building query bodies easier.
+TIP: https://github.com/danpaz/bodybuilder[bodybuilder] and https://github.com/sudo-suhas/elastic-builder[elastic-builder] can be used to make building query bodies easier.
 
 
 

docs/api_methods_5_2.asciidoc

@@ -1663,7 +1663,7 @@ client.search([params, [callback]])
 
 Return documents matching a query, aggregations/facets, highlighted snippets, suggestions, and more. Write your queries as either http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-uri-request.html[simple query strings] in the `q` parameter, or by specifying a http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-body.html[full request definition] using the http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html[Elasticsearch Query DSL] in the `body` parameter.
 
-TIP: https://github.com/danpaz/bodybuilder[bodybuilder], https://github.com/holidayextras/esq[esq], or https://github.com/sudo-suhas/elastic-builder[elastic-builder] can be used to make building query bodies easier.
+TIP: https://github.com/danpaz/bodybuilder[bodybuilder] and https://github.com/sudo-suhas/elastic-builder[elastic-builder] can be used to make building query bodies easier.
 
 
 

package.json

@@ -36,10 +36,7 @@
     "unstable_es_branches": [
       "5.x",
       "master"
-    ],
-    "branch_versions": {
-     "master": "6.0"
-    }
+    ]
   },
   "devDependencies": {
     "@spalger/eslint-config-personal": "^0.4.0",

scripts/Version.js

@@ -1,13 +1,34 @@
 var _ = require('lodash');
 var pkg = require('../package.json');
-var branches = pkg.config.supported_es_branches;
-var branchVersions = pkg.config.branch_versions;
+var branches = [...pkg.config.supported_es_branches, ...pkg.config.unstable_es_branches];
 var semver = require('semver');
 
-var maxMinorVersion = function (majorV) {
-  var versions = branches.map(function (v) { return v + '.0'; });
-  return new Version(semver.maxSatisfying(versions, '^' + majorV));
-};
+function nextMajorVersion() {
+  const largestMajor = branches
+    .map(v => parseFloat(v.split('.')[0]))
+    .filter(n => !isNaN(n))
+    .sort((a, b) => b - a)
+    .shift()
+
+  return new Version(`${largestMajor + 1}.0.0`)
+}
+
+function nextMinorVersion(major) {
+  const largestMinor = branches
+    .map(v => v.split('.').map(parseFloat).slice(0, 2))
+    // ensure all tuples have length 2
+    .filter(vt => vt.length === 2)
+    // ensure all values in tuples are not NaN
+    .filter(vt => vt.every(v => !isNaN(v)))
+    // ensure that major version in tuple matches major (both as a string)
+    .filter(vt => `${vt[0]}` === `${major}`)
+    // sort by the minor version in each tuple
+    .sort((vta, vtb) => vtb[1] - vta[1])
+    // get the minor version from the first tuple
+    .shift()[1];
+
+  return new Version(`${major}.${largestMinor + 1}.0`);
+}
 
 function Version(v) {
   this.version = v;
@@ -17,16 +38,15 @@ function Version(v) {
 }
 
 Version.fromBranch = function (branch) {
-  var m;
-
-  var branchVersion = branchVersions[branch];
-  var versionString = branchVersion ? branchVersion : branch;
-
   // n.m -> n.m.0
-  if (m = versionString.match(/^\d+\.\d+$/)) return new Version(versionString + '.0');
+  if (/^\d+\.\d+$/.test(branch)) return new Version(branch + '.0');
 
   // n.x -> n.(maxVersion + 1).0
-  if (m = versionString.match(/^(\d+)\.x$/i)) return maxMinorVersion(m[1]).increment('minor');
+  const match = branch.match(/^(\d+)\.x$/i)
+  if (match) return nextMinorVersion(match[1]);
+
+  // master => (maxMajorVersion + 1).0.0
+  if (branch === 'master') return nextMajorVersion()
 
   throw new Error('unable to convert branch "' + branch + '" to semver');
 };
@@ -36,6 +56,7 @@ Version.prototype.increment = function (which) {
 };
 
 Version.prototype.satisfies = function (range) {
+  debugger
   return semver.satisfies(this.version, range);
 };
 

scripts/generate/js_api.js

@@ -27,7 +27,8 @@ module.exports = function (branch, done) {
     mergeConcatParams: {},
     paramAsBody: {},
     clientActionModifier: false,
-    examples: {}
+    examples: {},
+    descriptions: {},
   });
 
   var steps = [
@@ -115,12 +116,19 @@ module.exports = function (branch, done) {
     [].concat(apiSpec.actions, apiSpec.proxies)
     .forEach(function (action) {
       var examplePath = overrides.examples[action.name] || action.name + '.asciidoc';
+      var descriptionPath = overrides.descriptions[action.name] || action.name + '.asciidoc';
 
       try {
         action.examples = fs.readFileSync(fromRoot('docs/_examples', examplePath), 'utf8');
       } catch (e) {
         action.examples = '// no examples';
       }
+
+      try {
+        action.description = fs.readFileSync(fromRoot('docs/_descriptions', descriptionPath), 'utf8');
+      } catch (e) {
+        action.description = '// no description';
+      }
     })
 
     done();

scripts/generate/overrides.js

@@ -249,9 +249,6 @@ function (spec) {
         '/_update_by_query/{task_id}/_rethrottle',
         '/_delete_by_query/{task_id}/_rethrottle'
       ]
-    },
-    examples: {
-      scroll: 'scroll_5.0+.asciidoc'
     }
   },
   {
@@ -266,5 +263,31 @@ function (spec) {
         body: 'scroll_id'
       }
     }
+  },
+  // description overrides by major version
+  {
+    version: '0.90.x',
+    descriptions: {
+      search: 'search_1.x.asciidoc'
+    }
+  },
+  {
+    version: '1.x',
+    descriptions: {
+      search: 'search_1.x.asciidoc'
+    }
+  },
+  {
+    version: '2.x',
+    descriptions: {
+      search: 'search_2.x.asciidoc'
+    }
+  },
+  // examples changed at 5.0
+  {
+    version: '<5.0.0',
+    examples: {
+      scroll: 'scroll_<5.0.asciidoc'
+    }
   }
 ];

scripts/generate/templates/api_methods.tmpl

@@ -21,7 +21,7 @@ _.each(actions, function (action) {
 client.<%= action.name %>([params, [callback]])
 --------
 
-<%= description(action.name) %>
+<%= action.description %>
 
 Check the *<<api-conventions>>* and <%= action.docUrl %>[the elasticsearch docs] for more information pertaining to this method.
 

scripts/generate/templates/index.js

@@ -54,18 +54,6 @@ var templateGlobals = {
     return block.split('\n\n').join('\n+\n');
   },
 
-  description: function (action) {
-    try {
-      return fs.readFileSync(path.join(__dirname, '../../../docs/_descriptions/' + action + '.asciidoc'));
-    } catch (e) {
-      if (~e.message.indexOf('ENOENT')) {
-        return '// no description';
-      } else {
-        throw e;
-      }
-    }
-  },
-
   paramType: function (type, paramName) {
     switch (type && type.toLowerCase ? type.toLowerCase() : 'any') {
       case 'time':