From 286a503cb6a1444a40c6af72651198d79d48b1fb Mon Sep 17 00:00:00 2001
From: Mitchell Hashimoto <mitchell.hashimoto@gmail.com>
Date: Sat, 25 Jan 2014 12:18:41 -0800
Subject: [PATCH] website/docs: docs for box versioning

---
 website/docs/Vagrantfile                      |  23 ++++
 website/docs/source/layouts/layout.erb        |   1 +
 website/docs/source/stylesheets/_base.less    |   2 +-
 website/docs/source/v2/boxes.html.md          |  92 +++++---------
 website/docs/source/v2/boxes/base.html.md     |   9 ++
 website/docs/source/v2/boxes/format.html.md   |  85 +++++++++++--
 .../docs/source/v2/boxes/versioning.html.md   |  95 +++++++++++++++
 website/docs/source/v2/cli/box.html.md        | 115 ++++++++++++++----
 8 files changed, 325 insertions(+), 97 deletions(-)
 create mode 100644 website/docs/Vagrantfile
 create mode 100644 website/docs/source/v2/boxes/versioning.html.md

diff --git a/website/docs/Vagrantfile b/website/docs/Vagrantfile
new file mode 100644
index 000000000..bab5d6429
--- /dev/null
+++ b/website/docs/Vagrantfile
@@ -0,0 +1,23 @@
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+# Vagrantfile API/syntax version. Don't touch unless you know what you're doing!
+VAGRANTFILE_API_VERSION = "2"
+
+$script = <<SCRIPT
+sudo apt-get -y update
+sudo apt-get -y install curl
+curl -sSL https://get.rvm.io | bash -s stable
+. ~/.bashrc
+. ~/.bash_profile
+rvm install 2.0.0
+rvm --default use 2.0.0
+cd /vagrant
+bundle
+SCRIPT
+
+Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
+  config.vm.box = "precise64"
+  config.vm.network "private_network", ip: "33.33.33.10"
+  config.vm.provision "shell", inline: $script, privileged: false
+end
diff --git a/website/docs/source/layouts/layout.erb b/website/docs/source/layouts/layout.erb
index ab7f31057..d46555ab5 100644
--- a/website/docs/source/layouts/layout.erb
+++ b/website/docs/source/layouts/layout.erb
@@ -139,6 +139,7 @@
 								<li<%= sidebar_current("boxes") %>><a href="/v2/boxes.html">Boxes</a></li>
 								<% if sidebar_section == "boxes" %>
 								<ul class="sub unstyled">
+									<li<%= sidebar_current("boxes-versioning") %>><a href="/v2/boxes/versioning.html">Box Versioning</a></li>
 									<li<%= sidebar_current("boxes-base") %>><a href="/v2/boxes/base.html">Creating a Base Box</a></li>
 									<li<%= sidebar_current("boxes-format") %>><a href="/v2/boxes/format.html">Box File Format</a></li>
 								</ul>
diff --git a/website/docs/source/stylesheets/_base.less b/website/docs/source/stylesheets/_base.less
index f898f2b06..d78333d04 100644
--- a/website/docs/source/stylesheets/_base.less
+++ b/website/docs/source/stylesheets/_base.less
@@ -87,7 +87,7 @@ h6 {
 	}
 
 p, td {
-	letter-spacing: 0.05em;
+	letter-spacing: normal;
 	line-height: 32px;
 
 	a {
diff --git a/website/docs/source/v2/boxes.html.md b/website/docs/source/v2/boxes.html.md
index 1d7ed3327..30c97c034 100644
--- a/website/docs/source/v2/boxes.html.md
+++ b/website/docs/source/v2/boxes.html.md
@@ -5,74 +5,44 @@ sidebar_current: "boxes"
 
 # Boxes
 
-Boxes are the skeleton from which Vagrant machines are constructed. They are
-portable files which can be used by others on any platform that runs Vagrant
-to bring up a working environment.
+Boxes are the package format for Vagrant environments. A box can be used by
+anyone on any platform that Vagrant supports to bring up an identical
+working environment.
 
 The `vagrant box` utility provides all the functionality for managing
-boxes. Boxes must currently be created manually.
+boxes. You can read the documentation on the [vagrant box](/v2/cli/box.html)
+command for more information.
 
-Boxes are [provider-specific](/v2/providers/index.html), so you must obtain
-the proper box depending on what provider you're using.
+The easiest way to use a box is to add a box from the
+[publicly available catalog of Vagrant boxes](#).
+You can also add and share your own customized boxes on this website.
 
-If you're interested in more details on the exact file format of
-boxes, there is a separate [page dedicated to that](/v2/boxes/format.html), since
-it is an advanced topic that general users don't need to know.
+Boxes also support versioning so that members of your team using Vagrant
+can update the underlying box easily, and the people who create boxes
+can push fixes and communicate these fixes efficiently.
 
-## Adding Boxes
+You can learn all about boxes by reading this page as well as the
+sub-pages in the navigation to the left.
 
-Adding boxes is straightforward:
+## Discovering Boxes
+
+The easiest way to find boxes is to look on the
+[public Vagrant box catalog](#)
+for a box matching your use case. The catalog contains most major operating
+systems as bases, as well as specialized boxes to get you up and running
+quickly with LAMP stacks, Ruby, Python, etc.
+
+The boxes on the public catalog work with many different
+[providers](/v2/providers/index.html). Whether you're using Vagrant with
+VirtualBox, VMware, AWS, etc. you should be able to find a box you need.
+
+Adding a box from the catalog is very easy. Each box shows you instructions
+with how to add it, but they all follow the same format:
 
 ```
-$ vagrant box add name url
+$ vagrant box add USER/BOX
+...
 ```
 
-`name` is a logical name by which the box is referenced from the
-Vagrantfile. You can put anything you want here, but know that Vagrant
-matches the `config.vm.box` directive with this name in order to look up
-the box to use.
-
-`url` is the location of the box. This can be a path to your local filesystem
-or an HTTP URL to the box remotely.
-
-Vagrant will automatically determine the provider the box was built
-for by reading the "metadata.json" file within the box archive. You
-may also tell Vagrant what provider the box is for by specifying the
-`--provider` flag.
-
-This is recommended as it adds an extra level of verification
-to the box you're downloading. Additionally, Vagrant can exit early with
-an error if a box with that name and provider already exists, whereas
-it must download the entire box before showing such an error in the other
-case.
-
-Multiple boxes with the same name can exist as long as they are all
-for different providers. The example of listing boxes below shows this,
-where there are multiple precise64 boxes, backed by different providers.
-This lets a single `config.vm.box` configuration within a Vagrantfile
-properly reference boxes across providers.
-
-## Listing Boxes
-
-To view what boxes Vagrant has locally installed, use `vagrant box list`:
-
-```
-$ vagrant box list
-precise64 (virtualbox)
-precise64 (vmware_fusion)
-```
-
-Vagrant lists all boxes along with the providers the box is for in parentheses.
-
-## Removing Boxes
-
-Boxes can be removed just as easily as they are added:
-
-```
-$ vagrant box remove precise64 virtualbox
-```
-
-The two arguments are the logical name of the box and the provider of the
-box. The second argument (the provider) is optional. If you have only a single
-provider backing that box, it doesn't need to be specified. If you have multiple
-providers backing a box and it isn't specified, Vagrant will show an error.
+For example: `vagrant box add hashicorp/precise64`. You can also quickly
+initialize a Vagrant environment with `vagrant init hashicorp/precise64`.
diff --git a/website/docs/source/v2/boxes/base.html.md b/website/docs/source/v2/boxes/base.html.md
index 6b4654f73..8f69159e3 100644
--- a/website/docs/source/v2/boxes/base.html.md
+++ b/website/docs/source/v2/boxes/base.html.md
@@ -180,6 +180,15 @@ Packaging the box into a `box` file is provider-specific. Please refer to
 the provider-specific documentation for creating a base box. Some
 provider-specific guides are linked to towards the top of this page.
 
+## Distributing the Box
+
+You can distribute the box file however you'd like. However, if you want
+to support versioning, putting multiple providers at a single URL, pushing
+updates, analytics, and more, we recommend you add the box to
+[Vagrant Cloud](#).
+
+You can upload both public and private boxes to this service.
+
 ## Testing the Box
 
 To test the box, pretend you're a new user of Vagrant and give it a shot:
diff --git a/website/docs/source/v2/boxes/format.html.md b/website/docs/source/v2/boxes/format.html.md
index 415338216..8f15cc9dc 100644
--- a/website/docs/source/v2/boxes/format.html.md
+++ b/website/docs/source/v2/boxes/format.html.md
@@ -6,21 +6,82 @@ sidebar_current: "boxes-format"
 # Box File Format
 
 In the past, boxes were just [tar files](http://en.wikipedia.org/wiki/Tar_\(computing\))
-of VirtualBox exports. With Vagrant supporting multiple providers, box files
-are now tar files where the contents differ for each provider. They are
-still tar files, but they may now optionally be [gzipped](http://en.wikipedia.org/wiki/Gzip)
-as well.
+of VirtualBox exports. With Vagrant supporting multiple
+[providers](/v2/providers/index.html) and [versioning](/v2/boxes/versioning.html)
+now, box files are slightly more complicated.
 
-Box files made for Vagrant 1.0.x and VirtualBox continue to work with
-Vagrant 1.1+ and the VirtualBox provider.
+Box files made for Vagrant 1.0.x (the VirtualBox export tar files) continue
+to work with Vagrant today. When Vagrant encounters one of these old boxes,
+it automatically updates it internally to the new format.
 
-The only file required within a box is a "metadata.json" file. This is
-a [JSON](http://www.json.org/) file that has a top-level object that
-can contain any metadata about the box. Vagrant requires that a "provider"
-key exists in this metadata with the name of the provider the box is made
-for.
+Today, box files are split into two different components:
 
-The "metadata.json" file for a VirtualBox box:
+* Box Metadata - This is a JSON document that specifies the name of the box,
+  a description, available versions, available providers, and URLs to the
+  actual box files (next component) for each provider and version. If this
+  metadata doesn't exist, a box file can still be added directly, but it
+  will not support versioning and updating.
+
+* Box File - This is a compressed (tar, tar.gz, zip) file that is specific
+  to a single provider and can contain anything. Vagrant core doesn't ever
+  use the contents of this file. Instead, they are passed to the provider.
+  Therefore, a VirtualBox box file has different contents from a VMware
+  box file and so on.
+
+Each component is covered in more detail below.
+
+## Box Metadata
+
+The metadata is an optional component for a box (but highly recommended)
+that enables [versioning](/v2/boxes/versioning.html), updating, multiple
+providers from a single file, and more.
+
+<div class="alert alert-block alert-info">
+<strong>You don't need to manually make the metadata.</strong> If you
+have an account with <a href="#">Vagrant Cloud</a>, you
+can create boxes there, and Vagrant Cloud automatically creates
+the metadata for you. The format is still documented here.
+</div>
+
+It is a JSON document, structured in the following way:
+
+```json
+{
+  "name": "hashicorp/precise64",
+  "description": "This box contains Ubuntu 12.04 LTS 64-bit.",
+  "versions": [{
+    "version": "0.1.0",
+    "providers": [{
+      "name": "virtualbox",
+      "url": "http://somewhere.s3.com/precise64_010_virtualbox.box"
+    }]
+  }]
+}
+```
+
+As you can see, the JSON document can describe multiple versions of a box,
+multiple providers, and can add/remove providers in different versions.
+
+This JSON file can be passed directly to `vagrant box add` and Vagrant
+will install the proper version of the box. If multiple providers are
+available, Vagrant will ask what provider you want to use.
+
+## Box File
+
+The actual box file is the required portion for Vagrant. It is recommended
+you always use a metadata file alongside a box file, but direct box files
+are supported for legacy reasons in Vagrant.
+
+Box files are compressed using tar, tar.gz, or zip. The contents of the
+archive can be anything, and is specific to each
+[provider](/v2/providers/index.html). Vagrant core itself only unpacks
+the boxes for use later.
+
+Within the archive, Vagrant does expect a single file: "metadata.json".
+This is a JSON file that is completely unrelated to the above "box metadata"
+component. This file must contain at least the "provider" key with the
+provider the box is for. For example, if your box was for VirtualBox,
+the metadata.json would look like this:
 
 ```json
 {
diff --git a/website/docs/source/v2/boxes/versioning.html.md b/website/docs/source/v2/boxes/versioning.html.md
new file mode 100644
index 000000000..ab96d26c2
--- /dev/null
+++ b/website/docs/source/v2/boxes/versioning.html.md
@@ -0,0 +1,95 @@
+---
+page_title: "Box Versioning"
+sidebar_current: "boxes-versioning"
+---
+
+# Box Versioning
+
+Since Vagrant 1.5, boxes support versioning. This allows the people who
+make boxes to push updates to the box, and the people who use the box
+have a simple workflow for checking for updates, updating their boxes,
+and seeing what has changed.
+
+If you're just getting started with Vagrant, box versioning isn't too
+important, and we recommend learning about some other topics first. But
+if you're using Vagrant on a team or plan on creating your own boxes,
+versioning is very important. Luckily, having versioning built right in
+to Vagrant makes it easy to use and fit nicely into the Vagrant workflow.
+
+This page will cover how to use versioned boxes. It does _not_ cover how
+to update your own custom boxes with versions. That is covered in
+[creating a base box](/v2/boxes/base.html).
+
+## Viewing Versions and Updating
+
+You can view the versions a box has by calling `vagrant box info`. This
+command will refresh the metadata associated with a box and list all
+available versions for this box. `vagrant box list` only shows _installed_
+versions of boxes.
+
+You can check if the box you're using is outdated with `vagrant box outdated`.
+This can check if the box in your current Vagrant environment is outdated
+as well as any other box installed on the system.
+
+Finally, you can update boxes with `vagrant box update`. This will download
+and install the new box. This _will not_ magically update running Vagrant
+environments. If a Vagrant environment is already running, you'll have to
+destroy and recreate it to acquire the new updates in the box. The update
+command just downloads these updates locally.
+
+## Version Constraints
+
+You can constrain a Vagrant environment to a specific version or versions
+of a box using the [Vagrantfile](/v2/vagrantfile/index.html) by specifying
+the `config.vm.box_version` option.
+
+If this option is not specified, the latest version is always used. This is
+equivalent to specifying a constraint of ">= 0".
+
+The box version configuration can be a specific version or a constraint of
+versions. Constraints can be any combination of the following:
+`= X`, `> X`, `< X`, `>= X`, `<= X`, `~> X`. You can combine multiple
+constraints by separating them with commas. All the constraints should be
+self explanatory except perhaps for `~>`, known as the "pessimistic constraint".
+Examples explain it best: `~> 1.0` is equivalent to `>= 1.0, < 2.0`. And
+`~> 1.1.5` is equivalent to `>= 1.1.5, < 1.2.0`.
+
+You can choose to handle versions however you see fit. However, many boxes
+in the public catalog follow [semantic versioning](http://semver.org/).
+Basically, only the first number (the "major version") breaks backwards
+compatibility. In terms of Vagrant boxes, this means that any software that
+runs in version "1.1.5" of a box should work in "1.2" and "1.4.5" and so on,
+but "2.0" might introduce big changes that break your software. By following
+this convention, the best constraint is `~> 1.0` because you know it is safe
+no matter what version is in that range.
+
+Of course, you're free to use versions however you'd like!
+
+## Automatic Update Checking
+
+Using the [Vagrantfile](/v2/vagrantfile/index.html), you can also configure
+Vagrant to automatically check for updates during any `vagrant up`. This is
+disabled by default, but can easily be enabled with
+`config.vm.box_check_update = true` in your Vagrantfile.
+
+When this is enabled, Vagrant will check for updates on every `vagrant up`,
+not just when the machine is being created from scratch, but also when it
+is resuming, starting after being halted, etc.
+
+If an update is found, Vagrant will output a warning to the user letting
+them know an update is available. That user can choose to ignore the warning
+for now, or can update the box by running `vagrant box update`.
+
+Vagrant can not and does not automatically download the updated box and
+update the machine because boxes can be relatively large and updating the
+machine requires destroying it and recreating it, which can cause important
+data to be lost. Therefore, this process is manual to the extent that the
+user has to manually enter a command to do it.
+
+## Pruning Old Versions
+
+Vagrant does not automatically prune old versions because it doesn't know
+if they might be in use by other Vagrant environments. Because boxes can
+be large, you may want to actively prune them once in awhile using
+`vagrant box remove`. You can see all the boxes that are installed
+using `vagrant box list`.
diff --git a/website/docs/source/v2/cli/box.html.md b/website/docs/source/v2/cli/box.html.md
index dddfef532..e03b18164 100644
--- a/website/docs/source/v2/cli/box.html.md
+++ b/website/docs/source/v2/cli/box.html.md
@@ -13,23 +13,28 @@ The main functionality of this command is exposed via even more subcommands:
 
 * `add`
 * `list`
+* `outdated`
 * `remove`
 * `repackage`
+* `update`
 
 # Box Add
 
-**Command: `vagrant box add NAME URL`**
+**Command: `vagrant box add ADDRESS`**
 
-This adds a box at the given URL to Vagrant and stores it under the
-logical name `NAME`.
+This adds a box with the given address to Vagrant. The address can be
+one of three things:
 
-The URL may be a file path or an HTTP URL. For HTTP, basic authentication
-is supported and `http_proxy` environmental variables are respected. HTTPS
-is also supported.
+* A shorthand name from the
+[public catalog of available Vagrant images](#),
+such as "hashicorp/precise64".
 
-The name argument of this command is a _logical name_, meaning you can
-effectively choose whatever you want. This is the name that Vagrant searches
-for to match with the `config.vm.box` setting in Vagrantfiles.
+* File path or HTTP URL to a box in a [catalog](#).
+For HTTP, basic authentication is supported and `http_proxy` environmental
+variables are respected. HTTPS is also supported.
+
+* URL directly a box file. In this case, you must specify a `--name` flag
+(see below) and versioning/updates won't work.
 
 If an error occurs during the download or the download is interrupted with
 a Ctrl-C, then Vagrant will attempt to resume the download the next time it
@@ -38,21 +43,17 @@ after the initial download.
 
 ## Options
 
+* `--box-version VALUE` - The version of the box you want to add. By default,
+  the latest version will be added. The value of this can be an exact version
+  number such as "1.2.3" or it can be a set of version constraints. A version
+  constraint looks like ">= 1.0, < 2.0".
+
 * `--cacert CERTFILE` - The certificate for the CA used to verify the peer.
   This should be used if the remote end doesn't use a standard root CA.
 
 * `--cert CERTFILE` - A client certificate to use when downloading the box, if
   necessary.
 
-* `--checksum VALUE` - A checksum for the box that is downloaded. If specified,
-  Vagrant will compare this checksum to what is actually downloaded and will
-  error if the checksums do not match. This is highly recommended since
-  box files are so large. If this is specified, `--checksum-type` must
-  also be specified.
-
-* `--checksum-type TYPE` - The type of checksum that `--checksum` is if it
-  is specified. Supported values are currently "md5", "sha1", and "sha256".
-
 * `--clean` - If given, Vagrant will remove any old temporary files from
   prior downloads of the same URL. This is useful if you don't want Vagrant
   to resume a download from a previous point, perhaps because the contents
@@ -68,23 +69,66 @@ after the initial download.
   adding is for the given provider. By default, Vagrant automatically
   detects the proper provider to use.
 
+## Options for direct box files
+
+The options below only apply if you're adding a box file directly (when
+you're not using a catalog).
+
+* `--checksum VALUE` - A checksum for the box that is downloaded. If specified,
+  Vagrant will compare this checksum to what is actually downloaded and will
+  error if the checksums do not match. This is highly recommended since
+  box files are so large. If this is specified, `--checksum-type` must
+  also be specified. If you're downloading from a catalog, the checksum is
+  included within the catalog entry.
+
+* `--checksum-type TYPE` - The type of checksum that `--checksum` is if it
+  is specified. Supported values are currently "md5", "sha1", and "sha256".
+
+* `--name VALUE` - Logical name for the box. This is the value that you
+  would put into `config.vm.box` in your Vagrantfile. When adding a box from
+  a catalog, the name is included in the catalog entry and doesn't have
+  to be specified.
+
 # Box List
 
 **Command: `vagrant box list`**
 
 This command lists all the boxes that are installed into Vagrant.
 
+# Box Outdated
+
+**Command: `vagrant box outdated`**
+
+This command tells you whether or not the box you're using in
+your current Vagrant environment is outdated. If the `--global` flag
+is present, every installed box will be checked for updates.
+
+Checking for updates involves refreshing the metadata associated with
+a box. This generally requires an internet connection.
+
 ## Options
 
-* `--box-info` - If given, Vagrant will display the URL from where the box
-  has been downloaded and the date it was added
+* `--global` - Check for updates for all installed boxes, not just the
+  boxes for the current Vagrant environment.
 
 # Box Remove
 
-**Command: `vagrant box remove NAME PROVIDER`**
+**Command: `vagrant box remove NAME`**
 
-This command removes a box from Vagrant that matches the given name and
-provider.
+This command removes a box from Vagrant that matches the given name.
+
+If a box has multiple providers, the exact provider must be specified
+with the `--provider` flag. If a box has multiple versions, you can select
+what versions to delete with the `--box-version` flag.
+
+## Options
+
+* `--box-version VALUE` - Version of version constraints of the boxes to
+  remove. See documentation on this flag for `box add` for more details.
+
+* `--provider VALUE` - The provider-specific box to remove with the given
+  name. This is only required if a box is backed by multiple providers.
+  If there is only a single provider, Vagrant will default to removing it.
 
 # Box Repackage
 
@@ -96,3 +140,28 @@ directory so you can redistribute it.
 When you add a box, Vagrant unpacks it and stores it internally. The
 original `*.box` file is not preserved. This command is useful for
 reclaiming a `*.box` file from an installed Vagrant box.
+
+# Box Update
+
+**Command: `vagrant box update`**
+
+This command updates the box for the current Vagrant environment if there
+are updates available. The command can also update a specific box (outside
+of an active Vagrant environment), by specifying the `--box` flag.
+
+Note that updating the box will not update an already-running Vagrant
+machine. To reflect the changes in the box, you'll have to destroy and
+bring back up the Vagrant machine.
+
+If you just want to check if there are updates available, use the
+`vagrant box outdated` command.
+
+## Options
+
+* `--box VALUE` - Name of a specific box to update. If this flag is not
+  specified, Vagrant will update the boxes for the active Vagrant
+  environment.
+
+* `--provider VALUE` - When `--box` is present, this controls what
+  provider-specific box to update. This is not required unless the box has
+  multiple providers. Without the `--box` flag, this has no effect.