merge

.gitignore

@@ -7,4 +7,4 @@ _site
 *.pyc
 .sass-cache
 *.vulcanized.html
-*.sublime-*
+*.sublime-*

README.md

@@ -66,5 +66,44 @@ Last step is to push the docs to App Engine. In your `Polymer/docs` directory, r
 
 This script builds the site, api docs, runs Vulcanizer over the imports, and deploys to App Engine.
 
+## Polymer release
+
+When we push a new version of Polymer, the site should be updated to use it. In addition,
+the element reference and other projects will need updating.
+
+First, update the submodules in /docs:
+
+    git submodule update
+
+Update the projects:
+
+    cd polymer-all/projects
+    ../tools/bin/pull-all-projects.sh
+
+Then, update the elements and polyfills:
+
+    cd components
+    ../polymer-all/tools/bin/pull-all-polymer.sh
+    ../polymer-all/tools/bin/pull-all-elements.sh
+
+Once these are updated, you need to update some versions for the docs:
+
+- Increment the version in `app.yaml`;
+- Update the Polymer release version in `_config.yml`.
+- Add a link point link to the release notes in `changelog.md`.
+
+Build the docs:
+
+    grunt docs
+
+At this point, run the dev server and preview things locally to make sure nothing is terribly
+broken after Polymer and the elements have been updated. 
+
+Lastly, run the deploy script:
+
+    ./scripts/deploy_site.sh
+
+Last thing is to switch the app version in the App Engine admin console. To make the docs live, hit up https://appengine.google.com/deployment?&app_id=s~polymer-project and select the version you just deployed.
+
 [jekyll]: http://jekyllrb.com/
 [grunt]: http://gruntjs.com/

_config.yml

@@ -21,6 +21,6 @@ kramdown:
 # Site globals used throughout docs.
 load_platform: true
 project_title: Polymer
-latest_version: 0.1.2
+latest_version: 0.1.3
 add_permalinks: true # adds permalinks to heading tags.
 load_disqus: true

app.yaml

@@ -1,5 +1,9 @@
 application: polymer-project
+<<<<<<< HEAD
 version: newsite
+=======
+version: 20140116
+>>>>>>> master
 runtime: python27
 api_version: 1
 threadsafe: yes

changelog.md

@@ -40,6 +40,12 @@ including polyfill repos, tools, projects, and UI elements.
 #### Shadow DOM
 {% endcomment %}
 
+## 2014-01-16 {#r2014-01-16}
+
+See the [full list of changes](https://github.com/Polymer/polymer/releases/tag/0.1.3).
+
+---
+
 ## 2014-01-09 {#r2014-01-09}
 
 See the [full list of changes](https://github.com/Polymer/polymer/releases/tag/0.1.2).

polymer.md

@@ -270,16 +270,32 @@ of the same name.
 There are two ways to publish properties:
 
 1. **Preferred** - Include its name in the `<polymer-element>`'s `attributes` attribute.
-1. Include the name in a `publish` object on your prototype.
+2. Include the name in a `publish` object on your prototype.
 
-As an example, here's an element that publishes three public properties, `foo`, `bar`, and `baz`:
+As an example, here's an element that publishes three public properties, `foo`, `bar`, and `baz`, using the `attributes` attribute:
 
     <polymer-element name="x-foo" attributes="foo bar baz">
       <script> 
         Polymer('x-foo');
       </script>
     </polymer-element>
 
+And here's one using the `publish` object:
+
+    <polymer-element name="x-foo">
+      <script> 
+        Polymer('x-foo', {
+          publish: {
+            foo: 'I am foo!',
+            bar: 'Hello, from bar',
+            baz: 'Baz up in here'
+          }
+        });
+      </script>
+    </polymer-element>
+
+Let's look at the difference between the two and when you might prefer one option over the other.
+
 #### Default property values
 
 By default, properties defined in `attributes` are `null`:
@@ -290,7 +306,7 @@ By default, properties defined in `attributes` are `null`:
       </script>
     </polymer-element>
 
-As such, you can provide default values using the `prototype`:
+As such, you can provide default values using a combination of the `attributes` attribute and the `prototype`:
 
     <polymer-element name="x-foo" attributes="bar">
       <script> 
@@ -300,7 +316,8 @@ As such, you can provide default values using the `prototype`:
       </script>
     </polymer-element>
 
-    <!-- Same, but using the alternate "publish" object. -->
+Or you can define the whole thing using the `publish` property:
+
     <polymer-element name="x-foo">
       <script> 
         Polymer('x-foo', {
@@ -310,7 +327,14 @@ As such, you can provide default values using the `prototype`:
         });
       </script>
     </polymer-element>
-
+
+Generally it's preferable to use the `attributes` attribute because it's the declarative approach and you can easily see all of the exposed properties at the top of the element.
+
+You should opt for the `publish` property when either of the following is true:
+
+1. Your element has many properties and placing them all on one line feels unwieldy.
+2. You want to define default values for you properties and prefer the DRYness of doing it all in one place.
+
 #### Configuring an element via attributes
 
 Attributes are a great way for users of your element to configure it, declaratively.