add a name: and mark it as required

src/site/docs/pub-package-manager/versioning.markdown

 ---
 layout: default
 title: "Pub: How does versioning work?"
 description: "How packages are versioned and how pub works with them."
 has-permalinks: true
 ---
 
 # {{ page.title }}
 
 One of pub's core concerns is helping you work with versioning. Here, I'll
@@ skipping 201 matching lines @@
 
 The fact that selecting a package version takes into account *every* package
 that depends on it has an important consequence: *the specific version that
 will be selected for a package is a global property of the app using that
 package.*
 
 I'll walk through an example so you can see what this means. Let's say we have
 two apps. Here are their pubspecs:
 
 {% highlight yaml %}
-# myapp
+name: my_app
 dependencies:
   widgets:
 {% endhighlight %}
 
 {% highlight yaml %}
-# otherapp
+name: other_app
 dependencies:
   widgets:
   collections: '<1.5.0'
 {% endhighlight %}
 
 They both depend on `widgets`, whose pubspec is:
 
 {% highlight yaml %}
-# widgets
+name: widgets
 dependencies:
   collections: '>=1.0.0 <2.0.0'
 {% endhighlight %}
 
-The `otherapp` package uses depends directly on `collections` itself. The
+The `other_app` package uses depends directly on `collections` itself. The
 interesting part is that it happens to have a different version constraint on
 it than `widgets` does.
 
 What this means is that you can't just look at the `widgets` package in
 isolation to figure out what version of `collections` it will use. It depends
-on the context. In `myapp`, `widgets` will be using `collections 1.9.9`. But
-in `otherapp`, `widgets` will get saddled with `collections 1.4.9` because of
+on the context. In `my_app`, `widgets` will be using `collections 1.9.9`. But
+in `other_app`, `widgets` will get saddled with `collections 1.4.9` because of
 the *other* constraint that `otherapp` places on it.
 
 This is why each app gets its own "packages" directory: The concrete version
 selected for each package depends on the entire dependency graph of the
 containing app.
 
 ## Lockfiles
 
 So once pub has solved your app's version constraints, then what? The end
 result is a complete list of every package that your app depends on either
@@ skipping 56 matching lines @@
 
 As you're selecting versions of packages, they are changing the shape of
 the dependency graph itself. As the graph changes, that may change
 constraints, which can cause you to select different versions, and then you
 go right back around in a circle.
 
 Sometimes this process never settles down into a stable solution. Gaze into
 the abyss:
 
 {% highlight yaml %}
-# myapp 0.0.0
+name: myapp

[Bob Nystrom, 2012/08/29 17:47:32]

my_app to be consistent with above?

[sethladd, 2012/08/29 19:49:18]

Done.

+version: 0.0.0
 dependencies:
   yin: '>=1.0.0'
 {% endhighlight %}
 
 {% highlight yaml %}
-# yin 1.0.0
+name: yin
+version: 1.0.0
 dependencies:
 {% endhighlight %}
 
 {% highlight yaml %}
-# yin 2.0.0
+name: yin
+version: 2.0.0
 dependencies:
   yang: '1.0.0'
 {% endhighlight %}
 
 {% highlight yaml %}
-# yang 1.0.0
+name: yang
+version: 1.0.0
 dependencies:
   yin: '1.0.0'
 {% endhighlight %}
 
 In all of these cases, there is no set of concrete versions that will work for
 your app, and when this happens pub will report an error and tell you what's
 going on. It definitely will not try to leave you in some weird state where you
 think things can work but won't.
 
 ## Summary
 
 Wow, that's a lot to get through. Here's the important bits:
 
  *  Code reuse is great, but in order to let developers move quickly, packages
     need to be able to evolve independently.
  *  Versioning is how you enable that. But depending on single concrete versions
     is too precise and with shared dependencies leads to version lock.
  *  To cope with that, you depend on *ranges* of versions. Pub will then walk
     your dependency graph and pick the best versions for you. If it can't, it
     tells you.
  *  Once your app has a solid set of versions for its dependencies, that gets
     pinned down in a *lockfile*. That ensures that every machine your app is
     on is using the same versions of all of its dependencies.