Merge lp://staging/~julian-edwards/maas/releasenotes-1.6 into lp://staging/maas/1.6

The special notice is useful, but not very clear I think, from the standpoint of someone who doesn't yet know what it's about. Maybe split this up into sentences conveying separate points of information? 1. Cluster interfaces now have "static IP ranges." 2. These are needed in order to give stable IP addresses to nodes. 3. You need to edit them.

The IP Addresses Overhaul section has a complete afterthought in parentheses. I would recommend making that a separate sentence. It can still be in parentheses, as long as the previous sentence clearly ends before the parenthetical text. Otherwise you're asking the reader to keep the whole thing in mind, just in case the original sentence resumes after the parenthetical remark.

This sentence looks like it's sort of the wrong way around:

«Additionally, only addresses in the new static range will receive DNS entries for cluster interfaces that provide DNS management.»

The text looks as if the DNS entries are “for” cluster interfaces when really it's more as if they're received “from” cluster interfaces.

Suggestion:

«The DNS server built into MAAS will only provide IP addresses in this static range.»

The heading "IP Addresses Overhaul" heading is capitalised differently from the other ones.

.

Phrasing is a bit roundabout throughout the second half of this paragraph:

«DNS entries
  In 1.5 DNS entries for nodes were a CNAME record. As of 1.6, they are now
  all "A" records, and the pre-generation of the entire range defined in the
  zone is now not done (to speed up the job that writes the zone). This
  means that depending on DNS entries for unallocated nodes is no longer
  possible.»

I suspect that the need to explain pre-generation first is what makes this hard to formulate. Forces you to go through things in an awkward order. Maybe the reader doesn't really need to know about pre-generation as such? Because in that case, I think you could cover the subject with:

 1. Unallocated nodes no longer have DNS entries.
 2. Host names are now mapped as A records.
 3. Therefore, reverse lookup now works!
 4. DNS management is faster.

.

Instead of this:

«Existing nodes still require editing to change the installer in use, however.»

I would say something like:

«By default, existing nodes will keep using the installer they used before.»

—assuming that's what you mean, of course.

.

Thanks for taking care of this chore!

> The special notice is useful, but not very clear I think, from the standpoint of someone who doesn't yet know what it's about. Maybe split this up into sentences conveying separate points of information? 1. Cluster interfaces now have "static IP ranges." 2. These are needed in order to give stable IP addresses to nodes. 3. You need to edit them.

I've reworded it along your lines, thanks.

> The IP Addresses Overhaul section has a complete afterthought in parentheses. I would recommend making that a separate sentence. It can still be in parentheses, as long as the previous sentence clearly ends before the parenthetical text. Otherwise you're asking the reader to keep the whole thing in mind, just in case the original sentence resumes after the parenthetical remark.

Done!

> Suggestion:
> «The DNS server built into MAAS will only provide IP addresses in this static range.»

I've reworded it as this is not quite true any more, thanks.

> The heading "IP Addresses Overhaul" heading is capitalised differently from the other ones.

Oops, fixed.

> I suspect that the need to explain pre-generation first is what makes this hard to formulate. Forces you to go through things in an awkward order. Maybe the reader doesn't really need to know about pre-generation as such? Because in that case, I think you could cover the subject with:
>
> 1. Unallocated nodes no longer have DNS entries.
> 2. Host names are now mapped as A records.
> 3. Therefore, reverse lookup now works!
> 4. DNS management is faster.

Done.

> I would say something like:
>
> «By default, existing nodes will keep using the installer they used before.»
>
> —assuming that's what you mean, of course.

Yes, and done.

> Thanks for taking care of this chore!

It keeps me out of trouble.

And thanks for the reviewing chore!

Might be worth mentioning that the cluster<->region communications now requires arbitrary high-numbered port connections. See https://bugs.launchpad.net/maas/+bug/1352923 for details.

> Might be worth mentioning that the cluster<->region communications now
> requires arbitrary high-numbered port connections. See
> https://bugs.launchpad.net/maas/+bug/1352923 for details.

What I meant is that, when we fix this, we will still require a range of ports to be open for cluster<->region communication (I assume we will fix the bug linked above this way); this should probably be mentioned in the release notes.

On Monday 11 Aug 2014 13:06:43 you wrote:
> > Might be worth mentioning that the cluster<->region communications now
> > requires arbitrary high-numbered port connections. See
> > https://bugs.launchpad.net/maas/+bug/1352923 for details.
>
> What I meant is that, when we fix this, we will still require a range of
> ports to be open for cluster<->region communication (I assume we will fix
> the bug linked above this way); this should probably be mentioned in the
> release notes.

Urgh, right. Gavin, do we have any idea of what a rough range of the ports
will be? I can't just say "any old high-numered ports", people will rightly
laugh.