[dojo-contributors] Shipping Dojo 1.7

I attempted to make one at the top of this thread. I'll update it.
Anything missing?

release notes: ready to go (any takers for review?)
ref-guide needs to be pushed with necessary infrastructure work,
codeglass, more? (Pete)
cdn: ready at http://archive.dojotoolkit.org/cdn/ to send to Google (Pete)
api docs: publish 1.7 xml (Tom, done)
update website (Torrey)
announce on dojo-interest, other PR (Pete, Dylan, others?)

Looks like a good list. I'm not sure if the release notes need to be
updated for CDN or not. Guess we'll find out after Pete pushes to google.

I had asked Rawld about the veracity of a couple of notes in the release
notes a week or so ago but never got a response; specifically
http://livedocs.dojotoolkit.org/releasenotes/1.7#script and
http://livedocs.dojotoolkit.org/releasenotes/1.7#global-variables.

Anyone else have any ideas on whether these are true or not? At the
very least I could've sworn loading layers via script tags still worked,
though loading source modules may not. The 2nd section, about global
variables, just sounds completely off to me, but maybe it's due to the
way the examples are framed (inside plain script tags; maybe it's
supposed to be talking about modules?).

Also, we will have to update the reference guide link at the very top of
the release notes, to not point to livedocs.

Speaking of that blurb at the top, apologies for being blunt, but
calling the documentation "better than ever", at least in terms of the
wiki content, is somewhat laughable. Over the past few nights I have
been QA'ing articles regarding individual functions in Dojo core, and
even among those, I have found an alarming number of broken AMD-format
examples, mostly due to missing or wrong dependencies. On top of that,
others just don't follow the conventions we should be promoting. If we
expect people to be able to pick this up, the docs can't be wrong.

To that end, I'll continue doing what I can (I've been slowly working my
way down the dojo/index page - currently I'm midway through the
dojo/_base/html listing), just to make sure that existing examples
actually work, and improving wording/explanations where I deem necessary
and easily possible.

Some pages don't even have AMD-style examples (or even pages at all,
e.g. dojo.isDescendant and dojo.setSelectable which are listed on
dojo/_base/html), but I'm working under the prioritization that "wrong
docs are worse than no docs".

If anyone wants to help QA these things and wants to sync up, let me
know. (If you're an IRCer, hit me up on freenode as kgf, it'll probably
be easier to coordinate there.)

That said, I can't possibly expect this to be fully QA'd in any
"reasonable" amount of time if we want to "ship" soon. For that reason,
I would *strongly* urge that we do *something* to enable us to push
further fixes to reference-guide after the initial 1.7 push. This
hasn't been possible in the past because the wiki is "trunk" and there
is no "branching" of it, and thus once revisions specific to 1.8 start
coming in, it's too late.

I think Pete wants to look into getting rstwiki working locally again
this weekend, but I don't know how soon that can be put live; if it's
possible to kick that into gear sometime during 1.7's lifetime, allowing
us to fix doc issues as people find them rather than have them frozen in
time until 1.8, that would be great. We already had enough people
complain about the same handful of broken examples in the 1.6
reference-guide doc push over the last half year; it's likely to be even
more painful this time around.

Sorry for rambling so long. tl;dr - I'm working on ref-guide doc QA
when I can, and there's no way it'll be fit to ship too soon but I
presume that won't stop anyone (just like it didn't 2 weeks ago).

--Ken

I just improved the <script> section to be more accurate. You can't use script
injection with unbuilt code; you can use it with built code so long as you
build with the build flag "insertAbsMids" set to truthy. The reason for this
is that all of our modules are anonymous and there is no way to know what
module is being injected when provided by an explicit <script> element.
I agree. My opinion is that we can't advertise release until either

1.
the docs have been thoroughly QA'd and we know exactly their status

or

2.
the docs have been skimmed and we think they are good enough but we can
continue to improve the *1.7* docs without having to wait until 1.8.

I prefer [2].

Thanks for updating those sections, Rawld. The new wording is much clearer.

Out of your two choices RE docs and readiness, I'd probably agree #2 is
the more realistic of the two - assuming that getting rstwiki running
and being able to create a branch for 1.7 that we can easily redeploy is
more realistic than waiting a while for doc QA.

I realize though that choice #2 puts a lot of pressure on Pete. :/
Pete, I know Adam already voiced this at the last meeting, but if
there's some way other people can help... I'm gradually getting myself
knee-deep in docs at this point anyway so I might as well get used to
rstwiki if it can become a reality SRTL :P

--Ken

Me too.

Actually, my suggestion is to not branch the doc for a month or so, until
the 1.7 doc has settled. It would be too much of a hassle to merge all
these changes from the trunk to the branch (or vice-versa), whereas there's
no urgency to start adding documentation for 1.8 features [into the
reference manual], since those features are already being documented in
documents in google docs.

That also takes the pressure off of Pete somewhat.

I'd have to agree with Bill and Rawld on this one; getting rstwiki up and
running so that ref guide versions are *not* fixed should be the priority.

2011/11/13 Tom Trenka <ttrenka at gmail.com>

Actually, I was saying that we don't need to get rstwiki up and running.
We can use the same system that we've used for the past three years and
just release 1.7. We could still make updates to the reference doc and
publish it on our website before the 1.8 release.

But kgf tells me it looks like Pete has rstwiki working; if that's true
then I don't mind switching the "master copy" of the documentation to
github.

2011/11/12 Rawld Gill <rgill at altoviso.com>

I wrote the original section about globals, see
http://bugs.dojotoolkit.org/ticket/13217. You are right that the
examples were confusing.

But, note that even though mail.html loads src.js through a <script> tag,
it still doesn't work because the build modifies src.js by adding a
closure. Maybe that's because src.js is mentioned in the build profile.

Also note that this issue happens even though both files (mail.html and
src.js) are in the old format using dojo.provide() and dojo.require() and
not async:true, which is why it's listed in the migration section.

I will

* review the rel notes re loader, builder, bootstrap, base.
* add a *short* quickstart/overview about loader/builder
* review snover/kgf pullout of the loader doc
* pullout backcompat into a separate loader doc from the loader doc
* review the various messages/bugs I've rx'd over the last couple of weeks to
see if there are any show stoppers we need to be aware of re
loader/builder/boot.

I'll complete this before Monday morning.

Pete: could you delete 4 docs under
http://livedocs.dojotoolkit.org/developer/design:

*bootstrap (mostly incorporated in other docs)
*loader (now at /loader/legacy)
*loader/editor1 (now at /loader/amd)
*builder (now starts at /build)

There may be a couple of missing back INcompat notes missing re build
profiles. I have to analyze the bug reports more to figure this out. This
should *not* be a blocker.
After reviewing all the builder/loader tickets, I see a few minor bugs
(probably...maybe also user error) trickling in. I so nothing that I won't be
able to provide a work-around to...therefore, I see no blockers.


After spending a few hours this weekend on the project, my impression is...

* just like snover and kgf have been noting...1.7 is a little rough around
the edges, particularly docs. But it's a big release with tons of changes and
I don't see any particular item that could be called a blocker.

* because it is a little less polished that we'd like...we *must* be able to
work on improving both docs and code without having to wait until 1.8. iiuc,
we're planning on a fairly fast 1.7.1 to fix code issues and docs will be
updateable. Someone please correct me if I'm wrong.


--Rawld