builderator 1.1.9 → 1.1.10

data/docs/configuration.md

@@ -1,245 +0,0 @@
-Configuration DSL
-=================
-
-Builderator's configuration language is a Ruby DSL, composed of `attributes`,  which are grouped into `namespaces`. A `namespace` may be singular, or it may be part of a `collection`, in which case more than one named entry may be defined with the same `namespace`.
-
-Namespaces and collections can accessed with blocks, or with a fluent interface:
-
-```ruby
-aws do |a|
-  a.region = 'us-west-1'
-end
-
-## Is the same as
-aws.region = 'us-west-1'
-```
-
-Collections are sets of named items. Like namespaces, they can be accessed with blocks, or a fluent interface:
-
-```ruby
-profile :default do |default_profile|
-  default_profile.chef.run_list 'apt:default', 'redis:server', 'app::server'
-end
-
-profile(:default).chef.environment 'development'
-profile(:prod).chef.environment 'production'
-```
-
-In the example above, the same collection item is accessed twice. A second item is also defined in the same collection. The final result looks like:
-
-```json
-{
-  "profile": {
-    "default": {
-      "chef": {
-        "run_list": ["apt:default", "redis:server", "app::server"],
-        "environment": "development"
-      }
-    },
-    "prod": {
-      "chef": {
-        "environment": "production"
-      }
-    }
-  }
-}
-```
-
-Collections and namespaces may be nested indefinitely.
-
-## Extending Collection Items
-
-A collection item can extend another item using a hash-notation:
-
-```ruby
-profile :prod => Config.profile(:default) do |prod|
-  prod.chef.environment = 'production'
-end
-```
-
-Following the example, above, the `prod` profile will now be pre-populated with all of the values in the `default` profile, which can be overridden:
-
-```json
-{
-  "profile": {
-    "default": {
-      "chef": {
-        "run_list": ["apt:default", "redis:server", "app::server"],
-        "environment": "development"
-      }
-    },
-    "prod": {
-      "chef": {
-        "run_list": ["apt:default", "redis:server", "app::server"],
-        "environment": "production"
-      }
-    }
-  }
-}
-```
-
-## List-type Attributes
-
-Some configuration attributes are actually ordered sets of values. These are referred to as `list-type` attributes, and have some additional options:
-
-```ruby
-chef.run_list 'apt:default', :mode => :override
-```
-
-The `:mode` parameter tells the configuration manager how how to compile a list-type attribute that is defined in two or more layers, or is modified in an extended collection item. Currently, two modes are implemented:
-
-* `:override` - Instructs the compiler to discard any elements that have been loaded from lower layers. This does not have any effect upon the behavior of the same attribute in higher layers, meaning that the current layer's override may be appended to or overridden by future layers, according to their `mode` parameter.
-* `:union` - Default behavior. Instructs the compiler to perform a set-union between the current layer's elements and the current set of elements compiled from lower layers.
-
-List-type attributes may also have an `appender method`, which allows elements to be appended to the current set _in that layer_. **List-type attributes do not have an `=` setter.**
-
-Because `chef.run_list` is a list-type attribute, we can tell Builderator to override the `default` profile's `run_list`:
-
-```ruby
-profile :prod => Config.profile(:default) do |prod|
-  prod.chef.environment = 'production'
-  prod.chef.run_list 'apt:default', 'redis:server', 'app::server', 'app::tls', :mode => :override
-end
-```
-
-We could also append to `default`'s `run_list` without modifying `default`:
-
-```ruby
-profile :prod => Config.profile(:default) do |prod|
-  prod.chef.environment = 'production'
-  prod.chef.run_list_item 'app::tls'
-end
-```
-
-Both of the above will result in the same compiled configuration:
-
-```json
-{
-  "profile": {
-    "default": {
-      "chef": {
-        "run_list": ["apt:default", "redis:server", "app::server"],
-        "environment": "development"
-      }
-    },
-    "prod": {
-      "chef": {
-        "run_list": ["apt:default", "redis:server", "app::server", "app::tls"],
-        "environment": "production"
-      }
-    }
-  }
-}
-```
-
-## Helper Methods
-
-* `lookup(source, query)` - Query an external data-source for a value inline.
-* Source `:image`: Return an array of EC2 instances, sorted by `creation_date` (See http://docs.aws.amazon.com/sdkforruby/api/Aws/EC2/Client.html#describe_images-instance_method)
-
-* `vendored(name, path)` - Return the absolute path to `path` in the named vendor resource. _ Hint: Use this helper to reference Builderator policy files and Chef data_bag and environment sources in an external repository._
-
-* `relative(path)` - Return the absolute path to `path` relative to the calling Buildfile _Hint: Use this helper to reference templates included with a vendored policy._
-
-## Configuration Parameters
-
-* [Namespace `cookbook`](configuration/cookbook.md)
-* [Collection `profile`](configuration/profile.md)
-
-* `build_name, required: true` The name of the build
-* `build_number` Optional reference to the CI build number for this release
-* `build_url` Optional link the CI page for this release
-* `description` A short human-readable description of the build
-* `version` The version of this release of the build. Auto-populated by `autoversion` by default
-* `cleanup` Enable post-build cleanup tasks. Default `true`
-
-### Namespace `autoversion`
-
-* `create_tags` During a release, automatically create and push new SCM tags
-* `search_tags` Use SCM tags to determine the current version of the build
-
-### Namespace `chef`
-
-Global configurations for chef provisioners in Vagrant and Packer
-
-* `log_level` Chef client/solo log level
-* `staging_directory` the path in VMs and images that Chef artifacts should be mounted/copied to. Defaults to `/var/chef`
-* `version` The version of chef to install with Omnibus
-
-### Namespace `local`
-
-Local paths used for build tasks
-
-* `cookbook_path` Path at which to vendor cookbooks. Default `.builderator/cookbooks`
-* `data_bag_path` and `environment_path` Paths that Chef providers should load data-bag and environment documents from.
-
-### Collection `policy`
-
-Load additional attributes into the parent file from a relative path
-
-* `path` Load a DSL file, relative => true
-* `json` Load a JSON file relative => true
-
-### Namespace `aws`
-
-AWS API configurations. _Hint: Configure these in `$HOME/.builderator/Buildfile`, or use a built-in credential source, e.g. ~/.aws/config!_
-
-* `region` The default AWS region to use
-* `access_key` and `secret_key` A valid IAM key-pair
-
-### Collection `vendor`
-
-Fetch remote artifacts for builds
-
-* Sources:
-  * `path` Link to a local file/directory
-  * `git` Fetch a git repository
-  * `github` Fetch a git repository from a GitHub URI (e.g. `OWNER/REPO`) using the SSH protocol. You must have a valid SSH key configuration for public GitHub.
-* Git-specific parameters:
-  * `remote` - The name of the remote repository at `git` or `github`. Defaults to `origin`
-  * `branch` - The SCM branch to check out. Defaults to `master`
-  * `tag` or `ref` - A SHA-ish or SCM tag to check out. Overrides `branch`.
-  * `rel` Checkout a sub-directory of a git repository
-
-### Namespace `cleaner`
-
-Configuration parameters for `build-clean` tasks
-
-#### Namespace `limits`
-
-Maximum number of resources to remove without manual override
-
-* `images`
-* `launch_configs`
-* `snapshots`
-* `volumes`
-
-### Namespace `generator`
-
-Configurations for the `generator` task
-
-#### Collection `project`
-
-* `builderator.version` The version of Builderator to install with Bundler
-* `ruby.version` The version of ruby to require for Bundler and `rbenv`/`rvm`
-
-##### Namespace `vagrant`
-
-* `install` Boolean, include the vagrant gem from GitHub `mitchellh/vagrant`
-* `version` The version of Vagrant to use from GitHub, if `install` is true
-
-###### Collection `plugin`
-
-Vagrant plugins to install, either with the `build vagrant plugin` command, for a system-wide installation of Vagrant, or in the generated Gemfile if `install` is true
-
-##### Collection `resource`
-
-Add a managed file to the project definition
-
-* `action` One of
-  * `:create` Add a file from a template if it's missing
-  * `:sync` Create or update a file from a template, stopping to ask for instructions if the file exists and the templated output does not match
-  * `:ignore` Do nothing
-  * `:rm` Delete a file if it exists
-* `path` One or more path in the working directory the this resource manages. Action `:rm` will delete multiple files, while `:create` and `:sync` will only use the first element of the list as their destination.
-* `template` The path to an ERB template. Must be an absolute path: use the [helpers](#helpers) in the Buildfile namespace to extend paths inline.

data/docs/configuration/cookbook.md

@@ -1,27 +0,0 @@
-cookbook
-========
-
-* `path` The path to a local cookbook source, including a valid `metadata.rb` file.
-* `sources, type: list, singular: add_source, unique: true` Supermarket APIs to resolve cookbook dependencies from
-* `metadata` Boolean. Read dependencies from local cookbook metadata.
-
-## `depends name`
-
-Collection of declared cookbook dependencies. Options are passed to [Berkshelf](http://berkshelf.com/). Check out their docs for additional details.
-
-* `version` A version constraint spec for the cookbook
-* `git` A git URI from which to fetch the cookbook
-* `GitHub` A GitHub URL from which to fetch the cookbook
-* `branch` A branch reference from which to fetch the cookbook
-* `tag` A tag reference from which to fetch the cookbook
-* `ref` A comittish reference from which to fetch the cookbook
-* `rel` The sub-directory of a git repository to check out as a cookbook
-* `path` The path to a local cookbook, relative to the build workspace.
-
-## Tasks
-
-* `berks metadata COOKBOOK` Generates a `metadata.json` file from a local cookbook's `metadata.rb` file. The specified `COOKBOOK` must be in the `cookbook.depends` collection with a valid `path` attribute.
-* `berks vendor` Resolve and fetch cookbooks for the `cookbook.depends` collection and store in `$VENDOR_PATH/cookbooks`
-* `berks upload` Upload the resolved dependency set for `cookbook.depends` to the Chef Server configured in Berkshelf's configuration (default `$HOME/.berkshelf/config.json`)
-* `berks clean` Removes the project's cookbook vendor cache.
-* `berks uncache` is a helper to clear Berkshelf's host-cache, in `$HOME/.berkshelf/cookbooks` by default.

data/docs/configuration/profile.md

@@ -1,122 +0,0 @@
-Collection `profile`
-====================
-
-A profile is a combination of Chef parameters, and Vagrant and Packer configurations. Profiles should provide
-
-* `tags, type: hash` EC2 tags to apply to instances and AMIs
-* `log_level` Chef log-level. Default `:info`
-
-## Collection `artifact`
-
-An externally managed resource to push to VMs and image builds, e.g. `bundle.tar.gz` from a Maven build.
-
-* `path` The workspace-rooted path to the artifact
-* `destination` The absolute path on the VM or image at which the artifact should be placed
-
-## Namespace `chef`
-* `run_list, type: list, singular: run_list_item, unique: true` The Chef runlist for this profile
-* `environment` The Chef environment to load for this
-* `node_attrs, type: hash` A hash of node attributes for this profile
-
-
-## Namespace `packer`
-
-Packer configurations for this profile
-
-### Collection `build`
-
-Add a packer build
-
-* `type` the build provider (e.g. amazon-ebs, virtualbox)
-* `instance_type` the EC2 instance type to use
-* `source_ami` The source AMI ID for an `amazon-ebs`
-* `ssh_username` Default `ubuntu`
-* `ami_virtualization_type` Default `hvm`
-* `tagging_role` the name of an IAM role that exists in each remote account that allows the AMI to be retagged
-
-  Example usage:
-
-  <pre>
-     profile bake: Config.profile(:default) do |bake|
-       bake.packer do |packer|
-         packer.build :default do |build|
-           build.tagging_role 'CreateTagsOnAllImages'
-         end
-       end
-     end
-  </pre>
-
-  Example IAM policy in remote account:
-
-  <pre>
-  {
-      "Version": "2012-10-17",
-      "Statement": [
-          {
-              "Sid": "StmtId",
-              "Effect": "Allow",
-              "Action": [
-                  "ec2:CreateTags"
-              ],
-              "Resource": [
-                  "*"
-              ]
-          }
-      ]
-  }
-  </pre>
-
-
-  The above policy needs to be assigned to a role that enables a trust relationship with the account that builds the AMI:
-
-  <pre>
-  {
-      "Version": "2012-10-17",
-      "Statement": [
-        {
-            "Effect": "Allow",
-            "Principal": {
-              "AWS": "arn:aws:iam::[ami_builder_account]:user/[ami_builder_user]"
-            },
-            "Action": "sts:AssumeRole"
-        }
-  }
-  </pre>
-
-## TODO: Share accounts
-
-* `ami_name` Name for new AMI
-* `ami_description` Description for the new AMI
-
-
-## Namespace `vagrant`
-
-Vagrant VM configurations
-
-### Namespace `local`
-
-Parameters for a local VM build
-
-* `provider` Default `virtualbox`
-* `box` Default `ubuntu-14.04-x86_64`
-* `box_url` Default `https://cloud-images.ubuntu.com/vagrant/trusty/current/trusty-server-cloudimg-amd64-vagrant-disk1.box`
-
-* `cpus` Default 2
-* `memory` Default 1024 (MB)
-
-## Namespace `ec2`
-
-Parameters for the provisioning EC2 nodes with Vagrant
-
-* `provider` Default `aws`
-* `box` Default `dummy`
-* `box_url` Default `https://github.com/mitchellh/vagrant-aws/raw/master/dummy.box`
-* `instance_type`
-* `source_ami`
-* `ssh_username`
-* `virtualization_type`
-* `iam_instance_profile_arn`
-* `subnet_id`
-* `security_groups, type: list, singular: security_group, unique: true`
-* `public_ip`
-* `ssh_host_attribute` One of: `[:public_ip_address, :dns_name, :private_ip_address]`, Default `:private_ip_address`

data/docs/versioning.md

@@ -1,65 +0,0 @@
-Versioning
-==========
-
-This functionality is currently supported for Git.
-
-## Version Bump Steps
-
-* `major` - Increment major version.
-* `major-prerelease` - Start a pre-release train from the next major version (increments major version).
-* `minor` - Increment minor version.
-* `minor-prerelease` - Start a pre-release train from the next minor version (increments minor version).
-* `patch` - Increment the patch version.
-* `patch-prerelease` - Force a new pre-release train from the next patch version, even if the current version is a pre-release.
-* `release` - Release a pre-release train a the current `major`.`minor`.`patch` version.
-* `prerelease NAME` Create or increment a pre-release version. If the current version is not a pre-release, the patch version will also be incremented.
-* `build` Add or increment a build number.
-
-Step types are an ordered-set. Incrementing a higher step resets all lower parameters.
-
-## Commands
-
-### `build version current`
-
-Searches for the newest SCM tag that is a valid sem-ver string and writes it to VERSION in the project root.
-
-### `build version bump [STEP [PRERELEASE_NAME=alpha]]`
-
-Increment the current version by the desired step and create a new SCM tag at HEAD.
-
-If STEP is omitted, Builderator will scan messages of commits between HEAD and the current version tag for hash-tag style annotations indicating how to increment the version, finally defaulting to a `patch` step if no annotations are found. If multiple `#STEP` annotations are detected, the largest (e.g. `#major` > `#patch`) step will be applied.
-
-## Configuration
-
-The `autoversion` namespace has two attributes:
-
-* `create_tags BOOLEAN` enables auto-generation of SCM tags after `bump` tasks. Default `false`.
-* `search_tags` enables detection of the current version from SCM tags. Default `true`.
-
-```ruby
-autoversion do |version|
-  version.create_tags false
-  version.search_tags true
-end
-```
-
-## Adding Providers
-
-SCM providers must extend the `Builderator::Control::Version::SCM` module, and must implement two methods in their singleton class:
-
-* `self._history` Return an array of hashes with the following keys:
-  - `:id` SCM commit identity
-  - `:message` SCM commit message
-  - `:tags` `nil` or an array of semver strings
-* `self.supported?` Return `true` if the provider supports the build environment (e.g. the `Git` provider checks that `pwd` is a git repository), else return `false`.
-
-To enable a provider module, pass it to `SCM.register`. See [Builderator::Control::Version::Git](blob/auto-version/lib/builderator/control/version/git.rb) for an example.
-
-## This looks like `thor-scmversion`
-
-_Why aren't you using `thor-scmversion`?!_
-
-Well yes, it's based upon `thor-scmversion`, which I've been using for a while. `thor-scmversion` provides a nice model to ensure correct versioning of automatically built modules, but the project is largely abandoned, lacks some key features required for Builderator, and has a very inefficient access path for reading Git SCM data.
-
-This implementation adds `TYPE-prerelease` bump steps, improves semver matching regular-expressions, dramatically improves git-data access time for repositories with many tags (only reads from git-blobs once),
-and de-couples core functionality for parsing and incrementing versions from Thor tasks and actual mutation of the repository.