Merge pull request #2318 from serverless/v0-v1-docs

Add comparison between 0.x and 1.x

docs/01-guide/08-serverless-variables.md

@@ -158,6 +158,18 @@ What this says is to use the `stage` CLI option if it exists, if not, use the de
 
 This overwrite functionality is super powerful. You can have as many variable references as you want, from any source you want, and each of them can be of different type and different name.
 
+## Setting the variable syntax
+
+You can overwrite the variable syntax in case you want to use a text for a config parameter that would clash with the variable syntax.
+
+```yml
+service: aws-nodejs # Name of the Service
+
+defaults:
+  variableSyntax: '\${{([\s\S]+?)}}' # Overwrite the default "${}" variable syntax to be "${{}}" instead. This can be helpful if you want to use "${}" as a string without using it as a variable.
+```
+
+
 # Migrating serverless.env.yml
 Previously we used the `serverless.env.yml` file to track Serverless Variables. It was a completely different system with different concepts. To migrate your variables from `serverless.env.yml`, you'll need to decide where you want to store your variables.
 

docs/01-guide/12-serverless-yml-reference.md

@@ -0,0 +1,39 @@
+<!--
+title: Serverless.yml reference
+menuText: Serverless.yml reference
+layout: Doc
+-->
+
+# Serverless.yml reference
+
+The following is a reference of all non provider specific configuration. The details of those config options and further options can be found in [our guide](./) and the provider [provider configuration](../02-providers).
+
+```yml
+service: aws-nodejs # Name of the Service
+
+defaults:  # default configuration parameters for Serverless
+  variableSyntax: '\${{([\s\S]+?)}}' # Overwrite the default "${}" variable syntax to be "${{}}" instead. This can be helpful if you want to use "${}" as a string without using it as a variable.
+
+provider: # Provider specific configuration. Check out each provider for all the variables that are available here
+  name: aws
+
+plugins:  # Plugins you want to include in this Service
+  - somePlugin
+
+custom:  # Custom configuration variables that should be used with the variable system
+  somevar: something
+
+package: # Packaging include and exclude configuration
+  exclude:
+    - exclude-me.js
+  include:
+    - include-me.js
+  artifact: my-service-code.zip
+
+functions: # Function definitions
+  hello:
+    handler: handler.hello
+    events:  # Events triggering this function
+
+resources: # Provider specific additional resources
+```

docs/01-guide/README.md

@@ -27,3 +27,4 @@ We always try to make our documentation better, so if you have feedback on the G
 - [Installing plugins](./09-installing-plugins.md)
 - [Including/Excluding files for deployment](./10-packaging.md)
 - [Environment variable handling](./11-environment-variable-handling.md)
+- [Serverless.yml reference](./12-serverless-yml-reference.md)

docs/02-providers/aws/README.md

@@ -23,7 +23,6 @@ provider:
   stage: dev # Set the default stage used. Default is dev
   region: us-east-1 # Overwrite the default region used. Default is us-east-1
   deploymentBucket: com.serverless.${self:provider.region}.deploys # Overwrite the default deployment bucket
-  variableSyntax: '\${{([\s\S]+?)}}' # Overwrite the default "${}" variable syntax to be "${{}}" instead. This can be helpful if you want to use "${}" as a string without using it as a variable.
 ```
 
 ### Deployment S3Bucket

docs/v0-v1-comparison.md

@@ -0,0 +1,42 @@
+<!--
+title: Version 0 to Version 1 comparison
+menuText: Comparison between 0.x and 1.x
+layout: Doc
+-->
+
+# Comparison between 0.x and 1.x of Serverless
+
+After the 0.5.6 release of Serverless we sat down with many contributors and users of the Framework to discuss the next steps to improve Serverless.
+Those discussions lead to our decision to completely rewrite Serverless. The configuration is in no way backwards compatible and can basically be seen as a completely new tool.
+
+We've decided to make this step so in the future we have a stronger base to work from and make sure we don't have to do major breaking changes like this anymore.
+
+Let's dig into the main differences between 0.x and 1.x to give you an idea how to start migrating your services. In general we've seen teams move from 0.x to 1.x in a relatively short amount of time, if you have any questions regarding the move please let us know in [our Forum](http://forum.serverless.com) or create [Issues in Github](https://github.com/serverless/serverless/issues).
+
+## Main differences between 0.x and 1.x
+
+As 1.x is a complete reimplementation without backwards compatibility pretty much everything is different. The following features are the most important ones to give you an understanding of where Serverless is moving.
+
+### Central configuration file
+
+In the past configuration was spread out over several configuration files. It was hard for users to have a good overview over all the different configuration values set for different functions. This was now moved into a central [serverless.yml file](./01-guide/12-serverless-yml-reference.md) that stores all configuration for one service. This also means there is no specific folder setup that you have to follow any more. By default Serverless simply zips up the folder your serverless.yml is in and deploys it to any functions defined in that config file (although you can [change the packaging behavior](./01-guide/10-packaging.md)).
+
+### Services are the main unit of deployment
+
+In the past Serverless didn't create a strong connection between functions that were deployed together. It was more for convenience sake that separate functions were grouped together. With 1.x functions now belong to a service. You can implement and deploy different services and while it's still possible to mix functions that are not related into the same service it's discouraged. Serverless wants you to build a micro-service architecture with functions being a part of that, but not the only part. You can read more about this in a past [blog post](https://serverless.com/blog/beginning-serverless-framework-v1/)
+
+### Built on CloudFormation
+
+With the move to a more service oriented style came the decision to move all configuration into CloudFormation. Every resource we create gets created through a central CloudFormation template. Each service gets its own CloudFormation stack, we even deploy new CF stacks if you create a service in a different stage. A very important feature that came with this move to CF was that you can now easily create any other kind of resource in AWS and connect it with your functions. You can read more about custom resources in [our guide](./01-guide/06-custom-provider-resources.md)
+
+### New plugin system
+
+While our old plugin system allowed for a powerful setup we felt we could push it a lot further and went back to the drawing board. We came up with a completely new way to build plugins for Serverless through hooks and lifecycle events. This is a breaking change for any existing plugin. You can read more about our Plugin system in our [extending serverless docs](./04-extending-serverless).
+
+### Endpoints are now events
+
+In 0.x APIG was treated as a separate resource and you could deploy endpoints separately. In 1.x APIG is just another event source that can be configured to trigger Lambda functions. We create one APIG per CloudFormation stack, so if you deploy to different stages we're creating separate API Gateways. You can read all about our [APIG integration in our event docs](./02-providers/aws/events/01-apigateway.md).
+
+## How to upgrade from 0.x to 1.x
+
+As Serverless 1.x is a complete reimplementation and does not implement all the features that were in 0.x (but has a lot more features in general) there is no direct update path. Basically the best way for users to move from 0.x to 1.x is to go through [our guide](./01-guide) and the [AWS provider documentation](./02-providers/aws) that will teach you all the details of Serverless 1.x. This should make it pretty easy to understand how to set up a service for 1.x and move your code over. We've worked with different teams during the Beta phase of Serverless 1.x and they were able to move their services into the new release pretty quickly.