Merge pull request serverless#2505 from serverless/version-lock

implement version check

docs/providers/aws/guide/v0_to_v1.md

@@ -1,7 +1,7 @@
 <!--
 title: Serverless Framework - AWS Lambda Guide - Comparison Of Serverless Framework V.1 & V.0
 menuText: V.0 & V.1
-menuOrder: 14
+menuOrder: 15
 description: A comparison of Serverless Framework V.1 and Serverless Framework V.0
 layout: Doc
 -->

docs/providers/aws/guide/version.md

@@ -0,0 +1,51 @@
+<!--
+title: Serverless Framework - AWS Lambda Guide - Pinning the Serverless framework version
+menuText: Version pinning
+menuOrder: 14
+description: How to pin a service to certain Serverless versions.
+layout: Doc
+-->
+
+# Why?
+
+The Serverless framework is usually installed globally via `npm install -g serverless`. This way you have the Serverless CLI available for all your services. Installing tools globally has the downside that the version can't be pinned inside package.json. This can lead to issues if you upgrade Serverless, but your colleagues or CI system don't. You can now use a new feature in your serverless.yaml which is available only in the latest version without worrying that your CI system will deploy with an old version of Serverless.
+
+## Pinning a Version
+
+To configure version pinning define a `frameworkVersion` property in your serverless.yaml. Whenever you run a Serverless command from the CLI it checks if your current Serverless version is matching the `frameworkVersion` range. The CLI uses [Semantic Versioning](http://semver.org/) so you can pin it to an exact version or provide a range. In general we recommend to pin to an exact version to ensure everybody in your team has the exact same setup and no unexpected problems happen.
+
+## Examples
+
+### Exact Version
+
+```yml
+# serverless.yml
+
+frameworkVersion: "=1.0.3"
+
+service: users
+
+provider:
+  name: aws
+  runtime: nodejs4.3
+  memorySize: 512
+
+…
+```
+
+### Version Range
+
+```yml
+# serverless.yml
+
+frameworkVersion: ">=1.0.0 <2.0.0"
+
+service: users
+
+provider:
+  name: aws
+  runtime: nodejs4.3
+  memorySize: 512
+
+…
+```

lib/classes/Service.js

@@ -4,6 +4,7 @@ const SError = require('./Error').SError;
 const path = require('path');
 const _ = require('lodash');
 const BbPromise = require('bluebird');
+const semver = require('semver');
 
 class Service {
 
@@ -52,6 +53,15 @@ class Service {
       .then((serverlessFileParam) => {
         const serverlessFile = serverlessFileParam;
         // basic service level validation
+        const version = this.serverless.utils.getVersion();
+        const ymlVersion = serverlessFile.frameworkVersion;
+        if (ymlVersion && !semver.satisfies(version, ymlVersion)) {
+          const errorMessage = [
+            `The Serverless version (${version}) does not satisfy the`,
+            ` "frameworkVersion" (${ymlVersion}) in serverless.yml`,
+          ].join('');
+          throw new SError(errorMessage);
+        }
         if (!serverlessFile.service) {
           throw new SError('"service" property is missing in serverless.yml');
         }

lib/classes/Service.test.js

@@ -3,6 +3,7 @@
 const path = require('path');
 const YAML = require('js-yaml');
 const expect = require('chai').expect;
+const sinon = require('sinon');
 const Service = require('../../lib/classes/Service');
 const Utils = require('../../lib/classes/Utils');
 const Serverless = require('../../lib/Serverless');
@@ -334,6 +335,53 @@ describe('Service', () => {
       });
     });
 
+    it('should throw error if frameworkVersion is not satisfied', () => {
+      const SUtils = new Utils();
+      const serverlessYml = {
+        service: 'service-name',
+        frameworkVersion: '=1.0.0',
+        provider: 'aws',
+        functions: {},
+      };
+      SUtils.writeFileSync(path.join(tmpDirPath, 'serverless.yml'),
+        YAML.dump(serverlessYml));
+
+      const serverless = new Serverless({ servicePath: tmpDirPath });
+      const getVersion = sinon.stub(serverless.utils, 'getVersion');
+      getVersion.returns('1.0.2');
+      serviceInstance = new Service(serverless);
+
+      return serviceInstance.load().then(() => {
+        // if we reach this, then no error was thrown as expected
+        // so make assertion fail intentionally to let us know something is wrong
+        expect(1).to.equal(2);
+      }).catch(e => {
+        expect(e.name).to.be.equal('ServerlessError');
+      });
+    });
+
+    it('should pass if frameworkVersion is satisfied', () => {
+      const SUtils = new Utils();
+      const serverlessYml = {
+        service: 'service-name',
+        frameworkVersion: '>=1.0.0',
+        provider: 'aws',
+        functions: {},
+      };
+      SUtils.writeFileSync(path.join(tmpDirPath, 'serverless.yml'),
+        YAML.dump(serverlessYml));
+
+      const serverless = new Serverless({ servicePath: tmpDirPath });
+      const getVersion = sinon.stub(serverless.utils, 'getVersion');
+      getVersion.returns('1.2.2');
+      serviceInstance = new Service(serverless);
+
+      return serviceInstance.load().then(() => {
+        // if this callbar is reached, then no error was thrown as expected
+        expect(1).to.equal(1);
+      });
+    });
+
     it('should not throw error if functions property is missing', () => {
       const SUtils = new Utils();
       const serverlessYml = {

lib/classes/Utils.js

@@ -9,12 +9,17 @@ const _ = require('lodash');
 const fetch = require('node-fetch');
 const uuid = require('uuid');
 const os = require('os');
+const version = require('../../package.json').version;
 
 class Utils {
   constructor(serverless) {
     this.serverless = serverless;
   }
 
+  getVersion() {
+    return version;
+  }
+
   dirExistsSync(dirPath) {
     try {
       const stats = fse.statSync(dirPath);

lib/plugins/create/templates/aws-java-gradle/serverless.yml

@@ -13,6 +13,10 @@
 
 service: aws-java-gradle # NOTE: update this with your service name
 
+# You can pin your service to only deploy with a specific Serverless version
+# Check out our docs for more details
+# frameworkVersion: "=X.X.X"
+
 provider:
   name: aws
   runtime: java8

lib/plugins/create/templates/aws-java-maven/serverless.yml

@@ -13,6 +13,10 @@
 
 service: aws-java-maven # NOTE: update this with your service name
 
+# You can pin your service to only deploy with a specific Serverless version
+# Check out our docs for more details
+# frameworkVersion: "=X.X.X"
+
 provider:
   name: aws
   runtime: java8

lib/plugins/create/templates/aws-nodejs/serverless.yml

@@ -13,6 +13,10 @@
 
 service: aws-nodejs # NOTE: update this with your service name
 
+# You can pin your service to only deploy with a specific Serverless version
+# Check out our docs for more details
+# frameworkVersion: "=X.X.X"
+
 provider:
   name: aws
   runtime: nodejs4.3

lib/plugins/create/templates/aws-python/serverless.yml

@@ -13,6 +13,10 @@
 
 service: aws-python # NOTE: update this with your service name
 
+# You can pin your service to only deploy with a specific Serverless version
+# Check out our docs for more details
+# frameworkVersion: "=X.X.X"
+
 provider:
   name: aws
   runtime: python2.7

lib/plugins/create/templates/aws-scala-sbt/serverless.yml

@@ -13,6 +13,10 @@
 
 service: aws-scala-sbt # NOTE: update this with your service name
 
+# You can pin your service to only deploy with a specific Serverless version
+# Check out our docs for more details
+# frameworkVersion: "=X.X.X"
+
 provider:
   name: aws
   runtime: java8