Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Edge change log in documentation #2092

Merged
merged 3 commits into from

6 participants

@philfreo

Since #2086 was well received, I thought I'd start us out.

Please review (in case my understanding of any changes was incorrect). And then of course we'll need to add whatever has changed regarding Model#change, silent, etc. -- but that I'm less sure about.

@tgriesser
Collaborator

I'm not sure about requiring pull requests to have changes to the docs, that could be taken care of after they're merged. I think just taking out the part below about not adding documentation would be enough (but that's just my opinion).

@tgriesser
Collaborator

model.change() has also been removed, with the simplification of the set internals - I'd taken that out from the docs earlier (wasn't entirely clear about the no docs modification).

Any change[:attr] are also no longer delayed until later when silent:true is passed, they are just completely silenced.

@acstll

This is great: "Model validation is now only enforced by default in Model#save"

I add an empty model to a collection to create a new entry on a CMS I'm building.

new: function () {
  this.collection.add({});
}

The main View listens for 'add' on the collection to show the Edit page.
Which is the same Edit page for editing existing entries.

I don't know how right or wrong my approach is but this change makes me happy.

@philfreo

If this is a good start overall I'd suggest merging it as is and then let others add in missing parts.

@tgriesser tgriesser merged commit e180e82 into from
@tgriesser
Collaborator

Thanks for taking care of this @philfreo - should help a lot with working on the latest edge!

@braddunbar
Collaborator

Wonderful. I think this will prevent a good many omissions/inconsistencies in the docs.

@jashkenas
Owner

I'm not sold on some of the changes here -- in particular:

If your pull request affects Backbone's public API, make relevant changes to
the documentation. If appropriate, also add a line in the "Change Log" section.

Tried it, and it usually works out terribly. The change log gets cluttered up with irrelevant things, and the documentation begins to be written in a schizophrenic style where everyone's pet feature begins to grow giant documentation sections.

  • Index.html should not refer to an unreleased version -- master should be in a state that's ready to be merged and tagged at any time.

  • Updating the docs "as you go" makes it extremely difficult to update them before tagging a release. It's hard to know what's been updated to match, and what was updated but then revised later. It's easier to push through the list of commits in GitX (or the equivalent) as you tag a release, and revise the documentation to suit.

I'll send a patch in a minute.

@philfreo

I care less about the documentation changes (though I still think it should be done) and more about having a changelog in master

master should be in a state that's ready to be merged and tagged at any time.

This is an argument to have a change log

@braddunbar
Collaborator

Index.html should not refer to an unreleased version -- master should be in a state that's ready to be merged and tagged at any time.

This is exactly the point, right? Without updated documentation master is still buggy and not ready for tagging.

Updating the docs "as you go" makes it extremely difficult to update them before tagging a release. It's hard to know what's been updated to match, and what was updated but then revised later. It's easier to push through the list of commits in GitX (or the equivalent) as you tag a release, and revise the documentation to suit.

I don't quite understand this. It reads as though you're saying it's harder if some of the work is already done? I think what's being proposed is that we skip that step altogether. If the docs in master are always correct (and being used, reviewed) there's no need for altering the docs before tagging.

@philfreo

Tried it, and it usually works out terribly. The change log gets cluttered up with irrelevant things, and the documentation begins to be written in a schizophrenic style where everyone's pet feature begins to grow giant documentation sections.

I appreciate this (Backbone docs are nice and clean), but it seems like edits/clean ups could be made either via feedback in pull requests, or by one of you guys soon after the code changes are merged in

@tgriesser
Collaborator

If we don't keep track of it in index.html, there needs to be somewhere that edge changes are logged, possibly a wiki page - that way it can be edited by anyone, and if someone notices there's a change made in master that wasn't added to the wiki they can go ahead and add it. I agree with @philfreo that unless you're here every day pouring over the commits, it would be a pain to work with master if there isn't somewhere documenting what's been changed.

@wookiehangover
Collaborator

What about using a wiki page or perpetually open issue to track the changes / additions / deletions between releases? That way its where any contributor can edit it (in the case of an issue) and we can keep track of changes without affecting index.html

@jashkenas
Owner

more about having a changelog in master

needs to be somewhere that edge changes are logged

What about using a wiki page or perpetually open issue to track the changes

Why trust in fallible Mankind when you can trust in Git?

For our purposes, where stuff is moving rapidly, and the place where you're recording the nature of the change is already captured (or should be) in the commit message, this is the superior "changelog" between releases:

0.9.10...master

@wookiehangover
Collaborator

As long as we don't have 9 months pass between releases I think that's workable... and that's what I used to get the changelog draft for 0.9.9, but it was a lot of work to sift through a few hundred commits.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.
Showing with 30 additions and 25 deletions.
  1. +4 −2 CONTRIBUTING.md
  2. +26 −23 index.html
View
6 CONTRIBUTING.md
@@ -2,8 +2,10 @@
* Before you open a ticket or send a pull request, [search](https://github.com/documentcloud/backbone/issues) for previous discussions about the same feature or issue. Add to the earlier ticket if you find one.
-* Before sending a pull request for a feature, be sure to have [tests](http://backbonejs.org/test/test.html).
+* Before sending a pull request for a feature or bug fix, be sure to have [tests](http://backbonejs.org/test/test.html).
+
+* If your pull request affects Backbone's public API, make relevant changes to the [documentation](https://github.com/documentcloud/backbone/blob/master/index.html). If appropriate, also add a line in the "Change Log" section.
* Use the same coding style as the rest of the [codebase](https://github.com/documentcloud/backbone/blob/master/backbone.js).
-* In your pull request, do not add documentation or re-build the minified `backbone-min.js` file. We'll do those things before cutting a new release.
+* In your pull request, do not re-build the minified `backbone-min.js` file. We'll do that before cutting a new release.
View
49 index.html
@@ -419,7 +419,6 @@
<li>– <a href="#View-dollar">$ (jQuery or Zepto)</a></li>
<li>– <a href="#View-render">render</a></li>
<li>– <a href="#View-remove">remove</a></li>
- <li>– <a href="#View-make">make</a></li>
<li>– <a href="#View-delegateEvents">delegateEvents</a></li>
<li>– <a href="#View-undelegateEvents">undelegateEvents</a></li>
</ul>
@@ -613,7 +612,14 @@ <h2 id="introduction">Introduction</h2>
to execute them.
</p>
- <h2 id="upgrading">Upgrading to 0.9.9</h2>
+ <h2 id="upgrading">Upgrading to Edge</h2>
+
+ <p>
+ You're reading the docs for an unreleased version. See the
+ <a href="#changelog">change log</a>.
+ </p>
+
+ <h2>Upgrading to 0.9.9</h2>
<p>
Backbone <b>0.9.9</b> should be considered as a release candidate
@@ -1269,9 +1275,10 @@ <h2 id="Model">Backbone.Model</h2>
<br />
This method is left undefined, and you're encouraged to override it with
your custom validation logic, if you have any that can be performed
- in JavaScript. <b>validate</b> is called before <tt>set</tt> and
- <tt>save</tt>, and is passed the model attributes, as well as the options
- from <tt>set</tt> or <tt>save</tt>.
+ in JavaScript. By default <b>validate</b> is called before
+ <tt>save</tt>, but can also be called before <tt>set</tt> if
+ <tt>{validate:true}</tt> is passed. The <b>validate</b> method is passed
+ the model attributes, as well as the options from <tt>set</tt> or <tt>save</tt>.
If the attributes are valid, don't return anything from <b>validate</b>;
if they are invalid, return an error of your choosing. It
can be as simple as a string error message to be displayed, or a complete
@@ -2537,24 +2544,6 @@ <h2 id="View">Backbone.View</h2>
events that the view has <a href="#Events-listenTo">listenTo</a>'d.
</p>
- <p id="View-make">
- <b class="header">make</b><code>view.make(tagName, [attributes], [content])</code>
- <br />
- Convenience function for creating a DOM element of the given type (<b>tagName</b>),
- with optional attributes and HTML content. Used internally to create the
- initial <tt>view.el</tt>.
- </p>
-
-<pre class="runnable">
-var view = new Backbone.View;
-
-var el = view.make("b", {"class": "bold"}, "Bold! ");
-
-$("#make-demo").append(el);
-</pre>
-
-<div id="make-demo"></div>
-
<p id="View-delegateEvents">
<b class="header">delegateEvents</b><code>delegateEvents([events])</code>
<br />
@@ -3824,6 +3813,20 @@ <h2 id="faq">F.A.Q.</h2>
<h2 id="changelog">Change Log</h2>
+ <b class="header">Edge</b> &mdash; <small><i>Not yet released</i></small> &mdash; <a href="https://github.com/documentcloud/backbone/compare/0.9.9...master">Diff</a><br />
+ <ul style="margin-top: 5px;">
+ <li>
+ Model validation is now only enforced by default in
+ <tt>Model#save</tt> and no longer enforced by default upon
+ construction or in <tt>Model#set</tt>, unless the
+ <tt>{validate:true}</tt> option is passed.
+ </li>
+ <li>
+ <tt>View#make</tt> has been removed. You'll need to use <tt>$</tt> directly to
+ construct DOM elements now.
+ </li>
+ </ul>
+
<b class="header">0.9.9</b> &mdash; <small><i>Dec. 13, 2012</i></small> &mdash; <a href="https://github.com/documentcloud/backbone/compare/0.9.2...0.9.9">Diff</a><br />
<ul style="margin-top: 5px;">
<li>
Something went wrong with that request. Please try again.