349423 - Release Notes for Bugzilla 3.0

Status: RESOLVED FIXED

(Bugzilla :: Documentation, defect)

Description

[Max Kanat-Alexander]

For Bugzilla 3.0, I'd like to do the release notes in HTML, in a template inside of Bugzilla itself, in the pages/ directory. We can link to it from the index page.

It would also make the copy that we have on the website look much nicer and much more readable.

The important question is, should we still keep around a text version of the release notes? Perhaps run HTML the release notes through w3m or lynx and keep pasting them to the top of the old rel_notes.txt in the docs/ directory.

Comment 1

[Colin Ogilvie [:cso]]

Seems a reasonable suggestion to me.

I'd like to keep a text version around too, though.

Comment 2

[Gervase Markham [:gerv]]

(In reply to comment #0)
> For Bugzilla 3.0, I'd like to do the release notes in HTML, in a template
> inside of Bugzilla itself, in the pages/ directory. We can link to it from the
> index page.

If we make the release notes require a working Bugzilla to read, which version do we link to from the website, where people want to read the release notes before they download? The one on landfill?

Gerv

Comment 3

[Max Kanat-Alexander]

(In reply to comment #2)
> If we make the release notes require a working Bugzilla to read, which version
> do we link to from the website, where people want to read the release notes
> before they download? The one on landfill?

  We'll copy the code into bugzilla.org, just like we did for the plain-text release notes, only it will be easier to read. The two sites have very similar Template-Toolkit structures, so it should be pretty easy.

Comment 4

[Max Kanat-Alexander]

Attachment: Work In Progress

Here's what I have so far.

Comment 5

[Frédéric Buclin]

Comment on attachment 236756 [details] [diff] [review]
Work In Progress

>Index: template/en/default/index.html.tmpl

>+  <p>Welcome to [% terms.Bugzilla %]. To see what's new in this version
>+    of Bugzilla, see the <a href="page.cgi?id=release-notes.html">release

Do not forget to replace Bugzilla by terms.Bugzilla on this last line.



>Index: template/en/default/pages/release-notes.html.tmpl

>+[% INCLUDE global/header.html.tmpl 
>+  title = "Bugzilla 3.0 Release Notes" 

Same here...

>+  <li><a href="#v30_upgrading">How to Upgrade From An Older Bugzilla</a></li>

And here, etc...

Or probably do we want "Bugzilla" to be displayed even if terms.Bugzilla is set to something else. In this case, we will have to hack 009bugwords.t to ignore this template.

Comment 6

[Max Kanat-Alexander]

Thanks for the comments.

Nah, I think we can use $terms.Bugzilla. That's fine.

Comment 7

[Max Kanat-Alexander]

Attachment: Work In Progress 2

Here's a bit more work done on it.

Comment 8

[Max Kanat-Alexander]

Note to self: I forgot to close the rl_contents <div>.

Comment 9

[David D. Kilzer (ddk)]

Comment on attachment 237245 [details] [diff] [review]
Work In Progress 2

>+  <li>If you hover your mouse over a full URL (like 
>+    <code>http://bugs.mycompany.com/show_bug.cgi?id=1212</code>) that 
>+    links to [% terms.abug %], you will see the title of the 
>+    [%+ terms.bug %].</li>

You may want to mention that this only works for links back to the same Bugzilla instance, not to external Bugzilla instances.  Also, the resolution status of the bug is displayed along with the title, just like "normal" bug links.  (This is a note for Bug 74355.)

Comment 10

[Marc Schumann [:Wurblzap]]

Comment on attachment 237245 [details] [diff] [review]
Work In Progress 2

I like it so far.

>+  # The Initial Developer of the Original Code is Everything Solved.
>+  # Portions created by Everything Solved are Copyright (C) 2006
>+  # Everything Solved. All Rights Reserved.

I don't know whether this may prevent derived works or restrict Bugzilla in any other way... If so, then it should go away.

Comment 11

[Max Kanat-Alexander]

(In reply to comment #10)
> I don't know whether this may prevent derived works or restrict Bugzilla in any
> other way... If so, then it should go away.

  That block is required by the Mozilla Public License. It must be in every file protected by the Mozilla Public License, because the Original Developer grants different rights than a Contributor, and there must *always* be an Original Developer.

  You can read the license here, if you'd like:

  http://www.mozilla.org/MPL/MPL-1.1-annotated.html

  Section 2 is the relevant section.

  I mark files I contribute as copyrighted by Everything Solved so that in the unlikely event that something happens to me or I disappear somewhere, you can still direct questions about license changes to the company. That's one of the major points of having these email addresses and copyrights, that if there are license questions or legal issues, these people are the people who have to be consulted.

Comment 12

[Max Kanat-Alexander]

Attachment: Work In Progress 3

Okay, here's more work that I did. I also updated the index a bit more and made the requirements more modular (so they actually use Bugzilla::Install::Requirements).

Comment 13

[Frédéric Buclin]

Comment on attachment 254891 [details] [diff] [review]
Work In Progress 3

>Index: template/en/default/index.html.tmpl

>+    You may also want to read the 
>+    <a href="docs/html/using.html">[% terms.Bugzilla %] User's Guide</a>

You must write: href="[% Param('doc_urlbase') %]using.html" as your doc may point elsewhere (which is e.g. my case).

Comment 14

[Max Kanat-Alexander]

Attachment: WIP 4

Here's the fourth work-in-progress.

Comment 15

[Max Kanat-Alexander]

Attachment: WIP 5

Comment 16

[Max Kanat-Alexander]

Attachment: WIP 6

Comment 17

[Max Kanat-Alexander]

Attachment: Actual WIP 6

Comment 18

[Max Kanat-Alexander]

Attachment: WIP 7: Contains all features

Okay, this set of release notes passes runtests, is valid HTML, and contains every new feature that I had marked with "relnote" on bmo.

It's not complete, because it still needs upgrade instructions and Outstanding Issues, but otherwise it's pretty good.

So did I miss any features? Any comments? Also, any thoughts on things that I should mark as Outstanding Issues (other than things that already exist in previous relnotes)?

Comment 19

[Frédéric Buclin]

Comment on attachment 255155 [details] [diff] [review]
WIP 7: Contains all features

>Index: template/en/default/pages/release-notes.html.tmpl

>+<ul class="bz_toc">

>+  <li>Obsolete Features</li>

You shouldn't display this item at all if there is nothing to say about it.


>+  <li><a href="#v30_issues">Outstanding Issues</a> (<strong>IMPORTANT, 
>+    PLEASE READ</strong>)</li>

This link doesn't work. We should add this section even if there is no issue to mention, and write a comment like "No outstanding issues so far" or "In preparation" in this section. I prefer explicit incomplete documentation than broken links.


>+  <li><a href="#v30_previous">Release Notes for Previous Versions</a></li>

Same comment here.


>+<p>If you're upgrading, make sure to read <a href="#v30_upgrading">How to
>+  Upgrade From An Older Version</a> and <a href="#v30_issues">Outstanding
>+  Issues</a>. If you are upgrading from a release before 2.22, make sure
>+  to read the release notes for all the <a href="#v30_previous">previous 
>+  versions</a> in between your version and [% terms.Bugzilla %] 3.0.</p>

Fixing my comments above would fix these links too. That's why it's better to have empty sections for now than no section at all.


>+<p>Note that future versions of [% terms.Bugzilla %] may require 
>+  MySQL 4.1.x.</p>

Wrong, we already require 4.1.2. Requirements for MySQL should be displayed using a similar UI than DBD::mysql.


>+[% PROCESS db_req db='pg' %]

We should also mention that we require Pg 8.0.0 or higher.


>+<h3><a name="v30_feat_sq"></a>Shared Saved Searches</h3>

>+<p>Users can control their shared and subscribed queries from
>+  the &quot;Prefs&quot; screen.</p>

"Prefs" is now "Preferences".


>+<h3><a name="v30_feat_qs"></a>QuickSearch Plugin for IE7 and Firefox 2</h3>

>+  This uses the 
>+  <a href="page.cgi?id=quicksearch.html">QuickSearch syntax</a>.</p>

Nit: a better and more complete description of what QuickSearch can do is page.cgi?id=quicksearchhack.html


>+<h3><a name="v30_feat_other"></a>Other Enhancements and Changes</h3>

>+  <li>If a [% terms.bug %] has flags set, and you move it to a different 
>+    product that has flags with the same name, the flags will be 
>+    preserved.</li>

Nit: ... assuming they pass validation checks. But maybe this precision is too technical for release notes.


>+  <li>When viewing [% terms.bug %] activity, fields that hold [% terms.bug %] 
>+    numbers (such as &quot;Blocks&quot;will have the [% terms.bug %] numbers
>+    displayed as links to those [% terms.bugs %].</li>

Missing ")" and whitespace after "Blocks".


>+  <li>In most places, the Version field is sorted using a version-sort
>+    (so 1.10 is greater than 1.2) instead of an alphabetical sort.</li>

No... we broke it since we use Object.pm from Version.pm. I thought I filed a bug about this problem already, but I cannot find it.


>+<h4>Enhancements For Administrators</h4>

>+  <li><kbd>sanitycheck.cgi</kbd> can now only be accessed by users
>+    in the <kbd>admin</kbd> group.</li>

No, that's the "editcomponents" group.


>+<h2><a name="v30_code_changes"></a>Code Changes Which May Affect 
>+  Customizations</h2>

>+  <li><a href="#v30_code_auth">Auth Re-write</a></li>

>+<h3><a name="v30_auth_rewrite"></a>Auth Re-write</h3>

The link doesn't work as it calls #v30_code_auth while the anchor name is v30_auth_rewrite.


>+<h3><a name="v30_code_obj"></a>Bugzilla::Object</h3>
>+
>+<p>There is a new base class for most of our objects, 
>+  <a href="[% Param('docs_urlbase') FILTER html %]">Bugzilla::Object</a>.

I suppose you mean api/Bugzilla/Object.html? Else this link is not very useful.


>+<h3><a name="v30_code_other"></a>Other Changes</h3>

>+  <li><code>checksetup.pl</code> has been completely re-written, and most
>+    of its code moved into modules in the <kbd>Bugzilla::Install</kbd>
>+    namespace. See the
>+    <a href="[% Param('docs_urlbase') FILTER html %]checksetup.html">checksetup
>+    documentation</a>

Missing "api/" before "checksetup.html".


>+[% BLOCK db_req %]

>+    <li><strong>perl module:</strong>
>+      [% m.dbd.module FILTER html %] v[% m.dbd.version FILTER html %]</li>

Must be [%+ %] else the module name is appended to "perl module:".


I have nothing else in mind which may be missing. So these release notes look great to me.

Comment 20

[Max Kanat-Alexander]

(In reply to comment #19)
> You shouldn't display this item at all if there is nothing to say about it.

  These release notes aren't complete. Didn't you see my comment above? :-)

> This link doesn't work. 

  Yes, there's this crazy thing in Bugzilla called "comments." :-)

> We should also mention that we require Pg 8.0.0 or higher.

  We do mention that. Did you see the actual page? I put the link into the Whiteboard.

> "Prefs" is now "Preferences".

  Okay, will fix.

> Nit: a better and more complete description of what QuickSearch can do is
> page.cgi?id=quicksearchhack.html

  Yeah, but that's linked from the page I linked to.

> Nit: ... assuming they pass validation checks. But maybe this precision is too
> technical for release notes.

  Yeah, I assumed it was too technical. :-) We can put details about that in the docs if we really want.

> No... we broke it since we use Object.pm from Version.pm. I thought I filed a
> bug about this problem already, but I cannot find it.

  Oh, we should fix that. It's a regression and it's really easy to fix (just override new_from_list).

> I have nothing else in mind which may be missing. So these release notes look
> great to me.

  Thanks! And thank you for your comments, I'll fix all that stuff soon. :-)

Comment 21

[Frédéric Buclin]

(In reply to comment #20)
>   Yes, there's this crazy thing in Bugzilla called "comments." :-)

But when re-reviewing a patch, I always read my previous review. So having mentioned it there will make me not forget to check this point later. ;)


> > We should also mention that we require Pg 8.0.0 or higher.
> 
>   We do mention that. Did you see the actual page?

I did, and it's not there. http://landfill.bugzilla.org/qa30/attachment.cgi?id=600 is what I see.

Comment 22

[Max Kanat-Alexander]

Attachment: Completed: v1

Okay, these release notes are completed! They are valid HTML, pass runtests, and contain no broken links.

Comment 23

[Max Kanat-Alexander]

Attachment: Completed: v2

I had forgotten to relnote mod_perl support! :-) That's fixed, now.

Comment 24

[Frédéric Buclin]

Comment on attachment 255807 [details] [diff] [review]
Completed: v2

>Index: template/en/default/pages/release-notes.html.tmpl

>+  <li>View the <a href="sanitycheck.cgi">Sanity Check</a> page on your

I don't think we should link to sanitycheck.cgi, either from this paragraph or from anywhere else in the docs. One reason is that the link may be invalid, such as with bugzilla.org.


>+  <li>Now follow the standard 
>+    <a href="http://www.bugzilla.org/docs/tip/html/installing-bugzilla.html">
>+    [%- terms.Bugzilla %] installation process</a>.</li>

Use Param('docs_urlbase').


Else this looks like a great piece of documentation. r=LpSolit

Comment 25

[Max Kanat-Alexander]

I left the links in there. I'm going to do something clever with the bugzilla.org version to make it link to landfill.

Checking in Bugzilla/Template.pm;
/cvsroot/mozilla/webtools/bugzilla/Bugzilla/Template.pm,v  <--  Template.pm
new revision: 1.68; previous revision: 1.67
done
Checking in docs/rel_notes.txt;
/cvsroot/mozilla/webtools/bugzilla/docs/rel_notes.txt,v  <--  rel_notes.txt
new revision: 1.44; previous revision: 1.43
done
RCS file: /cvsroot/mozilla/webtools/bugzilla/skins/standard/release-notes.css,v
done
Checking in skins/standard/release-notes.css;
/cvsroot/mozilla/webtools/bugzilla/skins/standard/release-notes.css,v  <--  release-notes.css
initial revision: 1.1
done
Checking in t/009bugwords.t;
/cvsroot/mozilla/webtools/bugzilla/t/009bugwords.t,v  <--  009bugwords.t
new revision: 1.5; previous revision: 1.4
done
Checking in template/en/default/index.html.tmpl;
/cvsroot/mozilla/webtools/bugzilla/template/en/default/index.html.tmpl,v  <--  index.html.tmpl
new revision: 1.33; previous revision: 1.32
done
RCS file: /cvsroot/mozilla/webtools/bugzilla/template/en/default/pages/release-notes.html.tmpl,v
done
Checking in template/en/default/pages/release-notes.html.tmpl;
/cvsroot/mozilla/webtools/bugzilla/template/en/default/pages/release-notes.html.tmpl,v  <--  release-notes.html.tmpl
initial revision: 1.1
done