[COOK-1820] - update readme wrt deprecated recipes

README.md

@@ -1,7 +1,11 @@
 Application cookbook
 ====================
 
-This cookbook is designed to be able to describe and deploy web applications. It provides the basic infrastructure; other cookbooks are required to support specific combinations of frameworks and application servers. The following cookbooks are available at this time:
+This cookbook is designed to be able to describe and deploy web
+applications. It provides the basic infrastructure; other cookbooks
+are required to support specific combinations of frameworks and
+application servers. The following cookbooks are available at this
+time:
 
 * application\_java (Java and Tomcat)
 * application\_nginx (nginx reverse proxy)
@@ -12,120 +16,158 @@ This cookbook is designed to be able to describe and deploy web applications. It
 Backward compatibility
 ----------------------
 
-Previous versions of this cookbook used a set of recipes, with the configuration stored in an `apps` data bag.
+As of version 2.0.0 of this cookbook, the recipes using configuration
+stored in the `apps` data bag are fully deprecated and removed.
+Version 1.0.4 of this cookbook is the last release where these recipes
+were available.
 
-This mode of operation has been DEPRECATED. The existing recipes will keep working for 3 months, and will then be removed. You are advised to upgrade your applications as soon as possible.
+See [COOK-1820](http://tickets.opscode.com/browse/COOK-1820).
 
 Requirements
 ============
 
 Chef 0.10.0 or higher required (for Chef environment use).
 
-The following Opscode cookbooks are dependencies, as this cookbook supports automating a large number of web application stacks.
-
-* runit
-* unicorn
-* passenger_apache2
-* tomcat
-* python
-* gunicorn
-* apache2
-* php
-
-Deprecated Recipes
-==================
-
-The following recipes are deprecated:
-
-* `default`
-* `django`
-* `gunicorn`
-* `java_webapp`
-* `mod_php_apache2`
-* `passenger_apache2`
-* `php`
-* `rails`
-* `tomcat`
-* `unicorn`
+The previous dependencies have been moved out to the
+application-stack-specific cookbooks, and this cookbook has no
+external dependencies.
 
 Resources/Providers
 ===================
 
-The `application` LWRP configures the basic properties of most applications, regardless of the framework or application server they use. These include:
+The `application` LWRP configures the basic properties of most
+applications, regardless of the framework or application server they
+use. These include:
 
-* SCM information for the deployment, such as the repository URL and branch name;
+* SCM information for the deployment, such as the repository URL and
+  branch name;
 * deployment destination, including the filesystem path to deploy to;
 * any OS packages to install as dependencies;
 * optional callback to control the deployment.
 
-This LWRP uses the `deploy_revision` LWRP to perform the bulk of its tasks, and many concepts and parameters map directly to it. Check the documentation for `deploy_revision` for more information.
+This LWRP uses the `deploy_revision` LWRP to perform the bulk of its
+tasks, and many concepts and parameters map directly to it. Check the
+documentation for `deploy_revision` for more information.
 
-Configuration of framework-specific aspects of the application are performed by invoking a sub-resource; see the appropriate cookbook for more documentation.
+Configuration of framework-specific aspects of the application are
+performed by invoking a sub-resource; see the appropriate cookbook for
+more documentation.
 
 # Actions
 
-- :deploy: deploy an application, including any necessary configuration, restarting the associated service if necessary
-- :force_deploy: same as :deploy, but it will send a :force\_deploy action to the deploy resource, directing it to deploy the application even if the same revision is already deployed
+- `:deploy`: deploy an application, including any necessary
+  configuration, restarting the associated service if necessary
+- `:force_deploy`: same as `:deploy`, but it will send a `:force_deploy`
+  action to the deploy resource, directing it to deploy the
+  application even if the same revision is already deployed
 
 # Attribute Parameters
 
-- name: name attribute. The name of the application you are setting up. This will be used to derive the default value for other attribute
-- packages: an Array or Hash of packages to be installed before starting the deployment
-- path: target path of the deployment; it will be created if it does not exist
-- owner: the user that shall own the target path
-- group: the group that shall own the target path
-- strategy: the underlying LWRP that will be used to perform the deployment. The default is `:deploy_revision`, and it should never be necessary to change it
-- scm_provider: the provider class to use for the deployment. It defaults to `Chef::Provider::Git`, you can set it to `Chef::Provider::Subversion` to deploy from an SVN repository
-- repository: the URL of the repository the application should be checked out from
-- revision: an identifier pointing to the revision that should be checkout out
-- deploy_key: the private key to use to access the repository via SSH
-- rollback\_on\_error: if true, exceptions during a deployment will be caught and a clean rollback to the previous version will be attempted; the exception will then be re-raised. Defaults to true; change it only if you know what you are doing
-- environment: a Hash of environment variables to set while running migrations
-- purge\_before\_symlink: an Array of paths (relative to the checkout) to remove before creating symlinks
-- create\_dirs\_before\_symlink: an Array paths (relative to the checkout) pointing to directories to create before creating symlinks
-- symlinks: a Hash of shared/dir/path => release/dir/path. It determines which files and dirs in the shared directory get symlinked to the current release directory
-- symlink\_before\_migrate: similar to symlinks, except that they will be linked before any migration is run
-- migrate: if `true` then migrations will be run; defaults to false
-- migration_command: a command to run to migrate the application from the previous to the current state
-- restart_command: a command to run when restarting the application
-- environment_name: the name of a framework-specific "environment" (for example the Rails environment). By default it is the same as the Chef environment, unless it is `_default`, in which case it is set to `production`
-- enable_submodules: whether to enable git submodules in the deploy,
+- `name`: name attribute. The name of the application you are setting
+  up. This will be used to derive the default value for other
+  attribute
+- `packages`: an Array or Hash of packages to be installed before
+  starting the deployment
+- `path`: target path of the deployment; it will be created if it does
+  not exist
+- `owner`: the user that shall own the target path
+- `group`: the group that shall own the target path
+- `strategy`: the underlying LWRP that will be used to perform the
+  deployment. The default is `:deploy_revision`, and it should never
+  be necessary to change it
+- `scm_provider`: the provider class to use for the deployment. It
+  defaults to `Chef::Provider::Git`, you can set it to
+  `Chef::Provider::Subversion` to deploy from an SVN repository
+- `repository`: the URL of the repository the application should be
+  checked out from
+- `revision`: an identifier pointing to the revision that should be
+  checked out
+- `deploy_key`: the private key to use to access the repository via SSH
+- `rollback_on_error`: if true, exceptions during a deployment will be
+  caught and a clean rollback to the previous version will be
+  attempted; the exception will then be re-raised. Defaults to true;
+  change it only if you know what you are doing
+- `environment`: a Hash of environment variables to set while running
+  migrations
+- `purge_before_symlink`: an Array of paths (relative to the checkout)
+  to remove before creating symlinks
+- `create_dirs_before_symlink`: an Array of paths (relative to the
+  checkout) pointing to directories to create before creating symlinks
+- `symlinks`: a Hash of shared/dir/path => release/dir/path. It
+  determines which files and dirs in the shared directory get
+  symlinked to the current release directory
+- `symlink_before_migrate`: similar to symlinks, except that they will
+  be linked before any migration is run
+- `migrate`: if `true` then migrations will be run; defaults to false
+- `migration_command`: a command to run to migrate the application from
+  the previous to the current state
+- `restart_command`: a command to run when restarting the application
+- `environment_name`: the name of a framework-specific "environment"
+  (for example the Rails environment). By default it is the same as
+  the Chef environment, unless it is `_default`, in which case it is
+  set to `production`
+- `enable_submodules`: whether to enable git submodules in the deploy,
   passed into the deploy resource.
 
 # Callback Attributes
 
-You can also set a few attributes on this LWRP that are interpreted as callback to be called at specific points during a deployment.
-If you pass a block, it will be evaluated within a new context. If you pass a string, it will be interpreted as a path (relative to the release directory) to a file; if it exists, it will be loaded and evaluated as though it were a Chef recipe.
+You can also set a few attributes on this LWRP that are interpreted as
+callback to be called at specific points during a deployment. If you
+pass a block, it will be evaluated within a new context. If you pass a
+string, it will be interpreted as a path (relative to the release
+directory) to a file; if it exists, it will be loaded and evaluated as
+though it were a Chef recipe.
 
 The following callback attributes are available:
 
-- before\_deploy: invoked immediately after initial setup and before the deployment proper is started. This callback will be invoked on every Chef run
-- before\_migrate
-- before\_symlink
-- before\_restart
-- after\_restart
+- `before_deploy`: invoked immediately after initial setup and before
+  the deployment proper is started. This callback will be invoked on
+  every Chef run
+- `before_migrate`
+- `before_symlink`
+- `before_restart`
+- `after_restart`
 
 # Sub-resources
 
-Anything that is not a known attribute will be interpreted as the name of a sub-resource; the resource will be looked up, and any nested attribute will be passed to it. More than one sub-resource can be added to an application; the order is significant, with the latter sub-resources overriding any sub-resource that comes before.
-
-Sub-resources can set their own values for some attributes; if they do, they will be merged together with the attribute set on the main resource. The attributes that support this behavior are the following:
-
-- environment: environment variables from the application and from sub-resources will be merged together, with later resources overriding values set in the application or previous resources
-- migration_command: commands from the application and from sub-resources will be concatenated together joined with '&&' and run as a single shell command. The migration will only succeed if all the commands succeed
-- restart_command: commands from the application and from sub-resources will be evaluated in order
-- symlink\_before\_migrate: will be concatenated as a single array
-- callbacks: sub-resources callbacks will be invoked first, followed by the application callbacks
+Anything that is not a known attribute will be interpreted as the name
+of a sub-resource; the resource will be looked up, and any nested
+attribute will be passed to it. More than one sub-resource can be
+added to an application; the order is significant, with the latter
+sub-resources overriding any sub-resource that comes before.
+
+Sub-resources can set their own values for some attributes; if they
+do, they will be merged together with the attribute set on the main
+resource. The attributes that support this behavior are the following:
+
+- `environment`: environment variables from the application and from
+  sub-resources will be merged together, with later resources
+  overriding values set in the application or previous resources
+- `migration_command`: commands from the application and from
+  sub-resources will be concatenated together joined with '&&' and run
+  as a single shell command. The migration will only succeed if all
+  the commands succeed
+- `restart_command`: commands from the application and from
+  sub-resources will be evaluated in order
+- `symlink_before_migrate`: will be concatenated as a single array
+- `callbacks`: sub-resources callbacks will be invoked first, followed
+  by the application callbacks
 
 Usage
 =====
 
-To use the application cookbook we recommend creating a cookbook named after the application, e.g. `my_app`. In `metadata.rb` you should declare a dependency on this cookbook and any framework cookbook the application may need. For example a Rails application may include:
+To use the application cookbook we recommend creating a cookbook named
+after the application, e.g. `my_app`. In `metadata.rb` you should
+declare a dependency on this cookbook and any framework cookbook the
+application may need. For example a Rails application may include:
 
     depends "application"
     depends "application_rails"
 
-The default recipe should describe your application using the `application` LWRP; you may also include additional recipes, for example to set up a database, queues, search engines and other components of your application.
+The default recipe should describe your application using the
+`application` LWRP; you may also include additional recipes, for
+example to set up a database, queues, search engines and other
+components of your application.
 
 A recipe using this LWRP may look like this:
 
@@ -146,14 +188,16 @@ A recipe using this LWRP may look like this:
       end
     end
 
-You can of course use any code necessary to determine the value of attributes:
+You can of course use any code necessary to determine the value of
+attributes:
 
     application "my_app" do
       repository "http://git.example.com/my-app.git"
       revision node.chef_environment == "production" ? "production" : "develop"
     end
 
-Attributes from the application and from sub-resources are merged together:
+Attributes from the application and from sub-resources are merged
+together:
 
     application "my_app" do
       restart_command "kill -1 `cat /var/run/one.pid`"
@@ -174,7 +218,8 @@ Attributes from the application and from sub-resources are merged together:
     # restart_command #=> kill -1 `cat /var/run/one.pid` && touch /tmp/something
     # environment #=> LC_ALL=en_US FOO=baz
 
-Most databases have the concept of migrations (or you can just use your own):
+Most databases have the concept of migrations (or you can just use
+your own):
 
     application "my_app" do
       path "/deploy/to/dir"
@@ -190,9 +235,12 @@ Most databases have the concept of migrations (or you can just use your own):
       end
     end
 
-This will run `your-applications-migrate-command`, with the current directory set to the directory of the current checkout.
+This will run `your-applications-migrate-command`, with the current
+directory set to the directory of the current checkout.
 
-To use the application cookbook, we recommend creating a role named after the application, e.g. `my_app`. Create a Ruby DSL role in your chef-repo, or create the role directly with knife.
+To use the application cookbook, we recommend creating a role named
+after the application, e.g. `my_app`. Create a Ruby DSL role in your
+chef-repo, or create the role directly with knife.
 
     % knife role show my_app -Fj
     {
@@ -212,12 +260,13 @@ To use the application cookbook, we recommend creating a role named after the ap
 License and Author
 ==================
 
-Author:: Adam Jacob (<adam@opscode.com>)
-Author:: Andrea Campi (<andrea.campi@zephirworks.com.com>)
-Author:: Joshua Timberman (<joshua@opscode.com>)
-Author:: Seth Chisamore (<schisamo@opscode.com>)
+- Author: Adam Jacob (<adam@opscode.com>)
+- Author: Andrea Campi (<andrea.campi@zephirworks.com.com>)
+- Author: Joshua Timberman (<joshua@opscode.com>)
+- Author: Noah Kantrowitz  (<noah@opscode.com>)
+- Author: Seth Chisamore (<schisamo@opscode.com>)
 
-Copyright 2009-2012, Opscode, Inc.
+- Copyright 2009-2012, Opscode, Inc.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.