You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lucene.apache.org by Chris Hostetter <ho...@fucit.org> on 2012/03/19 19:28:14 UTC
start being more official/vocal about "Wiki errata" pages for release
notes?
(some history for those who aren't away)
Something we've done on the Solr wiki since day one was have a wiki page
dedicated to each of the minor releases (with sub sections for any patch
releases) that lists info about the develompent of any releases that
haven't happened yet, and important notes about any releases that have
(recently we've started including a copy of hte release announcement)...
https://wiki.apache.org/solr/Solr3.6
https://wiki.apache.org/solr/Solr3.5
https://wiki.apache.org/solr/Solr3.4
...
https://wiki.apache.org/solr/Solr1.1
These pages initially served as simple info pages about the release, and
also as a place for documentation to link to when indicating what version
a feature became available. But over time, they've also served as
psuedo-errata pages in the rare case where something is overlooked in the
release notes of a release, for example...
https://wiki.apache.org/solr/Solr1.4
(proposal)
I think it would be a good idea to formalize this idea and start promoting
these type of pages for both Solr and Core, so that the top of README.txt
and CHANGES.txt for all of our future releases contained verbage such
as...
>> More information about this release, including any errata related to
>> the release notes, upgrade instructions, or other changes can be found
>> online at...
>> https://wiki.apache.org/lucene-java/Lucene3.6
...or...
>> https://wiki.apache.org/solr/Solr3.6
...we can also use these pages during development to collect the release
highlights that we intend to include in the rleease notes instead of the
existing "ReleaseNote36" type pages.
Comments / Objections?
-Hoss
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org
Re: start being more official/vocal about "Wiki errata" pages for
release notes?
Posted by Robert Muir <rc...@gmail.com>.
On Mon, Mar 19, 2012 at 3:28 PM, Chris Hostetter
<ho...@fucit.org> wrote:
> ...these pages would be entirely for end users, to consult when installing
> a release, in case there are any Errata information they should be aware
> of.
>
You can make such an errata page right now (maybe with empty errata)
and link it from wherever you want (including the actual release
note)?
Personally I'm not gonna be upset about it unless its a broken link.
--
lucidimagination.com
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org
Re: start being more official/vocal about "Wiki errata" pages for
release notes?
Posted by Chris Hostetter <ho...@fucit.org>.
: I don't think we should really set ourselves up for failure. Why can't
: we document the features in the release up-front and put time into
: trying to make it readable and concise, its going to be put on the
: website as well as sent via email to a ton of people, and maybe
: copy-pasted in blogs etc. Making it "live" won't fix those problems.
I'm not saying it will, i'm saying "mistakes happen, so let's prepare for
the possibility that they happen, and include in the releases a link to an
Errata for CHANGES.txt and README.txt"
: Its pretty relevant. What i'm saying the point of these pages is so
: the RM can type in TO: announce@, general@, and press ctrl-A, ctrl-C,
Ok, forget the fucking ReleaseNotes pages -- they can stay exactly as they
are, the purpose can remain exactly the same, and nothing i'm proposing
has to involve them in any way.
My suggestion to re-use/rename those pages was simply one of minimizing
duplication of content on the wiki as a whole -- i'm sorry for muddling
the issue, forget i ever mentioned anything about changing ReleaseNotes36
at all.
The crux of my suggestion was, and still is...
: Something we've done on the Solr wiki since day one was have a wiki page
: dedicated to each of the minor releases .. that lists info about the
: develompent of any releases that haven't happened yet, and important
: notes about any releases that have (recently we've started including a
: copy of hte release announcement)...
...
: ... But over time, they've also served as psuedo-errata pages
: in the rare case where something is overlooked in the release notes of a
: release, for example...
:
: https://wiki.apache.org/solr/Solr1.4
...
: I think it would be a good idea to formalize this idea and start promoting
: these type of pages for both Solr and Core, so that the top of README.txt and
: CHANGES.txt for all of our future releases contained verbage such as...
:
: >> More information about this release, including any errata related to the
: >> release notes, upgrade instructions, or other changes can be found online
: >> at...
: >> https://wiki.apache.org/lucene-java/Lucene3.6
: ...or...
: >> https://wiki.apache.org/solr/Solr3.6
...these pages would be entirely for end users, to consult when installing
a release, in case there are any Errata information they should be aware
of.
-Hoss
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org
Re: start being more official/vocal about "Wiki errata" pages for
release notes?
Posted by Robert Muir <rc...@gmail.com>.
On Mon, Mar 19, 2012 at 3:06 PM, Chris Hostetter
<ho...@fucit.org> wrote:
>
> : I don't understand the difference. If you are saying rename
> : ReleaseNote36 to Release36, then thats fine!
>
> the difference is we explicitly link to the URL of that page in the
> CHANGES.txt and README.txt with the verbage i suggested...
>
> ...and then if, after publishing the release, we realize we forgot to
> mention something in the README.txt or CHANGES.txt we update that wiki
> page to include it there.
I don't think we should really set ourselves up for failure. Why can't
we document the features in the release up-front and put time into
trying to make it readable and concise, its going to be put on the
website as well as sent via email to a ton of people, and maybe
copy-pasted in blogs etc. Making it "live" won't fix those problems.
But see below, I don't really care what happens to these pages after
they "serve their purpose" which is to prevent the RM from having to
go thru all the changes and try to figure out what they all mean,
which ones are really exciting to end users, and figure out how to
concisely word them, organize in some meaningful way, and then put
this all inside a nicely formatted email with correct grammar,
spelling, dates, release numbers.
>
> : at some point we are going to send an email with some contents, and if
> : thats gonna be me, I'm not going to type it up myself
> : but have it as a wiki page i copy-paste from... so I don't think it
> : should have other functionality/stuff on it...
> :
> : Does that make sense?
>
> not really -- but it's also not really relevant. there wouldn't *be* any
> other contents on that page when it's time to send the release
> announcement out, it would only get added after the release (if ever).
>
Its pretty relevant. What i'm saying the point of these pages is so
the RM can type in TO: announce@, general@, and press ctrl-A, ctrl-C,
ctrl-V, and send. They already have too much to worry about rather
than reformatting a wiki page with a different formatting. In other
words i think these release notes pages should be the *exact note*
along with formatting and everything so that its not all pushed onto
the RM.
After thats done, personally i dont care what happens to them (they
could be improved or whatever)....
--
lucidimagination.com
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org
Re: start being more official/vocal about "Wiki errata" pages for
release notes?
Posted by Chris Hostetter <ho...@fucit.org>.
: I don't understand the difference. If you are saying rename
: ReleaseNote36 to Release36, then thats fine!
the difference is we explicitly link to the URL of that page in the
CHANGES.txt and README.txt with the verbage i suggested...
>> More information about this release, including any errata related to
the release notes, upgrade instructions, or
>> other changes can be found online at...
>> https://wiki.apache.org/lucene-java/Lucene3.6
...or...
>> https://wiki.apache.org/solr/Solr3.6
...and then if, after publishing the release, we realize we forgot to
mention something in the README.txt or CHANGES.txt we update that wiki
page to include it there.
: at some point we are going to send an email with some contents, and if
: thats gonna be me, I'm not going to type it up myself
: but have it as a wiki page i copy-paste from... so I don't think it
: should have other functionality/stuff on it...
:
: Does that make sense?
not really -- but it's also not really relevant. there wouldn't *be* any
other contents on that page when it's time to send the release
announcement out, it would only get added after the release (if ever).
-Hoss
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org
Re: start being more official/vocal about "Wiki errata" pages for
release notes?
Posted by Robert Muir <rc...@gmail.com>.
On Mon, Mar 19, 2012 at 2:37 PM, Chris Hostetter
<ho...@fucit.org> wrote:
>
> : What is the purpose beyond release notes? The ReleaseNotes36 type
> : pages have a well-defined purpose, thats the exact release note we
> : will send out.
> : I think they are useful because it prevents the release manager from
> : having to do that work (other people can populate them with a summary
> : of the features).
> :
> : For more detailed stuff, we have CHANGES.txt, what you are suggesting
> : seems like a duplicate of that?
>
> your only considering the *pre* release use of this page (in which i'm
> suggestion it can be used *instead* of the ReleaseNotes36 page, not in
> adition to)
>
> *post* release if we discover "oh shit, we forgot to include LUCNEE-9999
> in the list of CHANGES.txt" or "damn, we really should have been more
> explicit about the importance of doing XYZ when upgrading" we can add that
> note to this wiki page -- the URL for which is already listed at the top
> of the CHANGE.txt as an important place for people to look for errata
> about the specific release they are using.
>
I don't understand the difference. If you are saying rename
ReleaseNote36 to Release36, then thats fine!
But as far as replacing the concept of ReleaseNote36 with some other
concept, this is impossible.
at some point we are going to send an email with some contents, and if
thats gonna be me, I'm not going to type it up myself
but have it as a wiki page i copy-paste from... so I don't think it
should have other functionality/stuff on it...
Does that make sense?
--
lucidimagination.com
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org
Re: start being more official/vocal about "Wiki errata" pages for
release notes?
Posted by Chris Hostetter <ho...@fucit.org>.
: What is the purpose beyond release notes? The ReleaseNotes36 type
: pages have a well-defined purpose, thats the exact release note we
: will send out.
: I think they are useful because it prevents the release manager from
: having to do that work (other people can populate them with a summary
: of the features).
:
: For more detailed stuff, we have CHANGES.txt, what you are suggesting
: seems like a duplicate of that?
your only considering the *pre* release use of this page (in which i'm
suggestion it can be used *instead* of the ReleaseNotes36 page, not in
adition to)
*post* release if we discover "oh shit, we forgot to include LUCNEE-9999
in the list of CHANGES.txt" or "damn, we really should have been more
explicit about the importance of doing XYZ when upgrading" we can add that
note to this wiki page -- the URL for which is already listed at the top
of the CHANGE.txt as an important place for people to look for errata
about the specific release they are using.
-Hoss
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org
Re: start being more official/vocal about "Wiki errata" pages for
release notes?
Posted by Robert Muir <rc...@gmail.com>.
On Mon, Mar 19, 2012 at 2:28 PM, Chris Hostetter
<ho...@fucit.org> wrote:
> ...we can also use these pages during development to collect the release
> highlights that we intend to include in the rleease notes instead of the
> existing "ReleaseNote36" type pages.
>
>
> Comments / Objections?
>
What is the purpose beyond release notes? The ReleaseNotes36 type
pages have a well-defined purpose, thats the exact release note we
will send out.
I think they are useful because it prevents the release manager from
having to do that work (other people can populate them with a summary
of the features).
For more detailed stuff, we have CHANGES.txt, what you are suggesting
seems like a duplicate of that?
--
lucidimagination.com
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org