Update version.yaml spec

plugin-updates.md

@@ -1,11 +1,11 @@
 # Version history
 
 - [Introduction](#introduction)
-- [Update process](#update-process)
-    - [Plugin dependencies](#plugin-dependencies)
-- [Plugin version file](#version-file)
-    - [Important updates](#important-updates)
-    - [Migration and seed files](#migration-seed-files)
+- [Update Process](#update-process)
+    - [Plugin Dependencies](#plugin-dependencies)
+- [Plugin Version File](#version-file)
+    - [Important Updates](#important-updates)
+    - [Migration and Seed Files](#migration-seed-files)
 
 <a name="introduction"></a>
 ## Introduction
@@ -24,7 +24,7 @@ The change log is stored in a YAML file called `version.yaml` inside the **/upda
             create_another_table.php    <=== Migration file
 
 <a name="update-process"></a>
-## Update process
+## Update Process
 
 During an update the system will notify the user about recent changes to plugins, it can also prompt them about [important or breaking changes](#important-updates). Any given migration or seed file will only be excuted once after a successful update. October executes the update process automatically when any of the following occurs:
 
@@ -35,7 +35,7 @@ During an update the system will notify the user about recent changes to plugins
 > **Note**: The plugin [initialization process](../plugin/registration#routing-initialization) is disabled during the update process, this should be a consideration in migration and seeding scripts.
 
 <a name="plugin-dependencies"></a>
-### Plugin dependencies
+### Plugin Dependencies
 
 Updates are applied in a specific order, based on the [defined dependencies in the plugin registration file](../plugin/registration#dependency-definitions). Plugins that are dependant will not be updated until all their dependencies have been updated first.
 
@@ -49,36 +49,32 @@ Updates are applied in a specific order, based on the [defined dependencies in t
 In the example above the **Acme.Blog** plugin will not be updated until the **Acme.User** plugin has been fully updated.
 
 <a name="version-file"></a>
-## Plugin version file
+## Plugin Version File
 
-The **version.yaml** file, called the *Plugin version file*, contains the version comments and refers to database scripts in the correct order. Please read the [Database structure](../database/structure) article for information about the migration files. This file is required if you're going to submit the plugin to the [Marketplace](http://octobercms.com/help/site/marketplace). Here is an example of a plugin version file:
+The **version.yaml** file, called the *Plugin Version File*, contains the version comments and refers to database scripts in the correct order. Please read the [Database structure](../database/structure) article for information about the migration files. This file is required if you're going to submit the plugin to the [Marketplace](http://octobercms.com/help/site/marketplace). Here is an example of a plugin version file:
 
-    1.0.1: "First version"
-    1.0.2: "Second version"
-    1.0.3:
+    "1.0.1": "First version"
+    "1.0.2": "Second version"
+    "1.0.3":
         - "Third version"
-        - "which has a lot of changes"
-        - "including this one"
-    1.1.0: "!!! Important update"
-    1.1.1:
+    "1.1.0": "!!! Important update"
+    "1.1.1":
         - "Update with a migration and seed"
-        - "and here's the migration"
-        - create_tables.php
-        - "and here's the seed"
-        - seed_the_database.php
+        - "create_tables.php"
+        - "seed_the_database.php"
 
-> **Note**: `version.yaml` files support having multiple text entries per version as the change log description. You can have as many update messages as you want, migration files can be listed in any position too.
+> **Note**: The `version.yaml` file should always use the first line for a text update that describes the changes and the remaining lines for update scripts. For more verbose updates, consider using a dedicated changelog file.
 
 As you can see above, there should be a key that represents the version number followed by the update message, which is either a string or an array containing update messages. For updates that refer to migration or seeding files, lines that are script file names can be placed in any position. An example of a comment with no associated update files:
 
-    1.0.1: "A single comment that uses no update scripts."
+    "1.0.1": "A single comment that uses no update scripts."
 
 <a name="important-updates"></a>
-### Important updates
+### Important Updates
 
-Sometimes a plugin needs to introduce features that will break websites already using the plugin. If an update comment in the **version.yaml** file begins with three exclamation marks (`!!!`) then it will be considered *Important* and will require the user to confirm before updating. An example of an important update comment:
+Sometimes a plugin needs to introduce features that will break websites already using the plugin. If an update comment in the **version.yaml** file begins with three exclamation marks (`!!!`) then it will be considered *Important* and will require the user to confirm before updating. An example of an important update comment is below.
 
-    1.1.0: "!!! This is an important update that contains breaking changes."
+    "1.1.0": "!!! This is an important update that contains breaking changes."
 
 When the system detects an important update it will provide three options to proceed:
 
@@ -89,14 +85,14 @@ When the system detects an important update it will provide three options to pro
 Confirming the comment will update the plugin as usual, or if the comment is skipped it will not be updated.
 
 <a name="migration-seed-files"></a>
-### Migration and seed files
+### Migration and Seed Files
 
 As previously described, updates also define when [migration and seed files](../database/structure) should be applied. An update line with a comment and updates:
 
-    1.1.1:
+    "1.1.1":
         - "This update will execute the two scripts below."
-        - some_upgrade_file.php
-        - some_seeding_file.php
+        - "some_upgrade_file.php"
+        - "some_seeding_file.php"
 
 The update file name should use *snake_case* while the containing PHP class should use *CamelCase*. For a file named **some_upgrade_file.php** the corresponding class would be `SomeUpgradeFile`.
 

themes-development.md

@@ -51,9 +51,9 @@ The theme version file **version.yaml** defines the current theme version and th
 
 The file format is following:
 
-    1.0.1: Theme initialization
-    1.0.2: Added more features
-    1.0.3: Some features are removed
+    "1.0.1": "Theme initialization"
+    "1.0.2": "Added more features"
+    "1.0.3": "Some features are removed"
 
 <a name="preview-image"></a>
 ## Theme Preview Image
@@ -141,8 +141,8 @@ A theme can depend on plugins by defining a **require** option in the [Theme inf
     # [...]
 
     require:
-        - Acme.User
-        - Acme.Blog
+        - "Acme.User"
+        - "Acme.Blog"
 
 When the theme is installed for the first time, the system will attempt to install the required plugins at the same time.