From 3ee1572e3ca8fe908bf053fdd3cc37da318ab076 Mon Sep 17 00:00:00 2001 From: Adam Spiers Date: Fri, 2 May 2014 21:36:42 +0100 Subject: [PATCH 1/5] use monospace for technical terms where appropriate --- website/docs/source/v2/boxes/format.html.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/website/docs/source/v2/boxes/format.html.md b/website/docs/source/v2/boxes/format.html.md index 411954c0a..372ae4710 100644 --- a/website/docs/source/v2/boxes/format.html.md +++ b/website/docs/source/v2/boxes/format.html.md @@ -10,7 +10,7 @@ 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 (the VirtualBox export tar files) continue +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. @@ -22,7 +22,7 @@ Today, box files are split into two different components: 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 +* 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 @@ -75,17 +75,17 @@ 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 +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". +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. Vagrant uses this to verify the provider of the box. For example, if your box was for VirtualBox, -the metadata.json would look like this: +the `metadata.json` would look like this: ```json { @@ -93,7 +93,7 @@ the metadata.json would look like this: } ``` -If there is no metadata.json file or the file does not contain valid JSON +If there is no `metadata.json` file or the file does not contain valid JSON with at least a "provider" key, then Vagrant will error when adding the box, because it can't verify the provider. From 606fc7a9e42d53381162992ccc910a5d16e9a737 Mon Sep 17 00:00:00 2001 From: Adam Spiers Date: Fri, 2 May 2014 21:38:25 +0100 Subject: [PATCH 2/5] eliminate slightly confusing wording It doesn't make sense to use the present tense when saying box files are split into two components, when one of those components is the box file and one is something else. One better way of phrasing it would be to use the past tense: "Box files were split into two separate components" but even that's not completely correct, because the old format did not include the metadata JSON document which is one of the new components. So it's safer to just say that today there are two different components. --- website/docs/source/v2/boxes/format.html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/source/v2/boxes/format.html.md b/website/docs/source/v2/boxes/format.html.md index 372ae4710..b40723d77 100644 --- a/website/docs/source/v2/boxes/format.html.md +++ b/website/docs/source/v2/boxes/format.html.md @@ -14,7 +14,7 @@ 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. -Today, box files are split into two different components: +Today, there are two different components: * Box Metadata - This is a JSON document that specifies the name of the box, a description, available versions, available providers, and URLs to the From 0f8183426ae7f9f42e5fed5972a01a60760f0684 Mon Sep 17 00:00:00 2001 From: Adam Spiers Date: Fri, 2 May 2014 21:43:38 +0100 Subject: [PATCH 3/5] reverse order of two box components The metadata is optional whereas the box file is required, so it makes sense to list the box file first. It's also easier on the reader's brain to start with the more obvious and easily understandable item (which they'll probably be expecting to read about anyway) and save the more surprising item till later. --- website/docs/source/v2/boxes/format.html.md | 78 ++++++++++----------- 1 file changed, 39 insertions(+), 39 deletions(-) diff --git a/website/docs/source/v2/boxes/format.html.md b/website/docs/source/v2/boxes/format.html.md index b40723d77..0554cfaff 100644 --- a/website/docs/source/v2/boxes/format.html.md +++ b/website/docs/source/v2/boxes/format.html.md @@ -16,20 +16,53 @@ it automatically updates it internally to the new format. Today, there are two different components: -* 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. +* 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. + Each component is covered in more detail below. +## 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. Vagrant uses this to verify the provider of the +box. For example, if your box was for VirtualBox, +the `metadata.json` would look like this: + +```json +{ + "provider": "virtualbox" +} +``` + +If there is no `metadata.json` file or the file does not contain valid JSON +with at least a "provider" key, then Vagrant will error when adding the box, +because it can't verify the provider. + +Other keys/values may be added to the metadata without issue. The value +of the metadata file is passed opaquely into Vagrant and plugins can make +use of it. At this point, Vagrant core does not use any other keys in this +file. + ## Box Metadata The metadata is an optional component for a box (but highly recommended) @@ -68,36 +101,3 @@ This JSON file can be passed directly to `vagrant box add` from the local filesystem using a file path or via a URL, 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. Vagrant uses this to verify the provider of the -box. For example, if your box was for VirtualBox, -the `metadata.json` would look like this: - -```json -{ - "provider": "virtualbox" -} -``` - -If there is no `metadata.json` file or the file does not contain valid JSON -with at least a "provider" key, then Vagrant will error when adding the box, -because it can't verify the provider. - -Other keys/values may be added to the metadata without issue. The value -of the metadata file is passed opaquely into Vagrant and plugins can make -use of it. At this point, Vagrant core does not use any other keys in this -file. From af09b81759be9461ddede67f251651daf8010b47 Mon Sep 17 00:00:00 2001 From: Adam Spiers Date: Fri, 2 May 2014 22:03:03 +0100 Subject: [PATCH 4/5] distinguish more clearly between two types of box metadata There are two types of box metadata, both in JSON format, so we need to minimise the potential for confusion between them. Renaming the component outside the box file to include the word "catalog" makes it clear that this JSON document can catalog potentially multiple boxes in one go. --- website/docs/source/v2/boxes/format.html.md | 29 +++++++++++++-------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/website/docs/source/v2/boxes/format.html.md b/website/docs/source/v2/boxes/format.html.md index 0554cfaff..6c64bd80a 100644 --- a/website/docs/source/v2/boxes/format.html.md +++ b/website/docs/source/v2/boxes/format.html.md @@ -22,11 +22,13 @@ Today, there are two different components: Therefore, a VirtualBox box file has different contents from a VMware box file and so on. -* 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 Catalog Metadata - This is a JSON document (typically exchanged + during interactions with [Vagrant Cloud](https://vagrantcloud.com)) + 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 catalog + metadata doesn't exist, a box file can still be added directly, but + it will not support versioning and updating. Each component is covered in more detail below. @@ -41,12 +43,17 @@ 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. Vagrant uses this to verify the provider of the -box. For example, if your box was for VirtualBox, -the `metadata.json` would look like this: +Within the archive, Vagrant does expect a single file: +`metadata.json`. This is a JSON file that is completely unrelated to +the above box catalog metadata component; there is only one +`metadata.json` per box file (inside the box file), whereas one +catalog metadata JSON document can describe multiple versions of the +same box, potentially spanning multiple providers. + +`metadata.json` must contain at least the "provider" key with the +provider the box is for. Vagrant uses this to verify the provider of +the box. For example, if your box was for VirtualBox, the +`metadata.json` would look like this: ```json { From 3a386f8bdece09f2cb818a643ce3c9b0ba2aa5eb Mon Sep 17 00:00:00 2001 From: Adam Spiers Date: Fri, 2 May 2014 22:10:40 +0100 Subject: [PATCH 5/5] mention that the "url" can also be a file path --- website/docs/source/v2/boxes/format.html.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/website/docs/source/v2/boxes/format.html.md b/website/docs/source/v2/boxes/format.html.md index 6c64bd80a..0eb584026 100644 --- a/website/docs/source/v2/boxes/format.html.md +++ b/website/docs/source/v2/boxes/format.html.md @@ -104,7 +104,8 @@ It is a JSON document, structured in the following way: 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` from the local -filesystem using a file path or via a URL, and Vagrant -will install the proper version of the box. If multiple providers are -available, Vagrant will ask what provider you want to use. +This JSON file can be passed directly to `vagrant box add` from the +local filesystem using a file path or via a URL, and Vagrant will +install the proper version of the box. In this case, the value for the +`url` key in the JSON can also be a file path. If multiple providers +are available, Vagrant will ask what provider you want to use.