You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lucene.apache.org by Doron Cohen <cd...@gmail.com> on 2008/01/25 01:40:09 UTC
formatable changes log
As it is becoming hard to browse/navigate CHANGES.txt, how about maintaining
it in a simple HTML file?
Requirements are:
- fancier formatting where adequate.
- collapse/expand by release/subject
- easy to maintain...
Here is an example, containing the current (new) trunk and 2.3.0 -
http://people.apache.org/~doronc/Changes.html
If people like it I will proceed with the rest of the content.
If not - other suggestions?
- Doron
Re: formatable changes log
Posted by DM Smith <dm...@gmail.com>.
Doron Cohen wrote:
> As it is becoming hard to browse/navigate CHANGES.txt, how about maintaining
> it in a simple HTML file?
>
> Requirements are:
> - fancier formatting where adequate.
> - collapse/expand by release/subject
> - easy to maintain...
>
> Here is an example, containing the current (new) trunk and 2.3.0 -
> http://people.apache.org/~doronc/Changes.html
>
> If people like it I will proceed with the rest of the content.
> If not - other suggestions?
>
> - Doron
>
>
I like it. Perhaps with a style sheet that will make it more obvious.
(I'll be glad to supply one in a little bit.)
And it will solve a charset problem I'm seeing in the file.
Under Testing for 2.3.0, there is an accented character that looks like
it is encoded in UTF-8 but it is coming across as multi-character.
I'm not sure that this will display what I am seeing in it, but as I
paste it, it shows the problem in my mail program:
Test Cases
1. LUCENE-766: Test adding two fields with the same name but different
term vector setting. (Nicolas Lalevée via Doron Cohen)
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: formatable changes log
Posted by Chris Hostetter <ho...@fucit.org>.
: - Need to define all developers/committers in front and assign each an ID,
: and use this ID when referring to them. I guess we can ignore this practice
...
: Person2). And BTW, AFAICT for now it does not support that P1 via P2 concept
: (though that can be requested as a new feature).
adding new committers to this list wouldn't be that bad ... it's not like
we have exponential growth of committers.
listing out all *contributors* would be a pain, but i think just ending
each descrption with "Patch courtesy of John Doe" instead of our current
"via" would probably be fine.
: The status.xml that needs to be maintained can be reviewed in
: http://people.apache.org/~doronc/status.xml - only two issues there now, but
: one can get the picture what it would take to maintain this file.
is the "type" attribute mandatory? the gifs it produces are kind of
anoying, and it seems to be somewhat reducndent with teh types of sections
(ie: contexts) we use ... then again, we could always start using "type"
for things like "new functionality" "updated api" etc, and make hte
contexts more specific to the code module (ie: one for each contrib, one
for search functionality, one for indexing functionality, one for
documentation, etc...) ... although that would make it harder to get an
overview of "what are the big changes" unless there are options for how ot
change the rendering of the file.
: To me the main disadvantage of using this is the need to run forrest with
: every commit to review the updated changes.html/pdf which I think is almost
: too much. Personally I am not very fond of editing XML files, but perhaps
: others are. (Editing the html file is not as simple as editing the txt file,
: but still I think way simpler than the XML.)
:
: So my preference so far is the HTML version, with a stylesheet(s).
we wouldn't neccessarily need to run forrest on every commit ... the
authoritative XML would be in SVN, and it's not too complex to read -- the
nightly builds would have the generated HTML/PDF versions (or do they?
does the nightly build run forrest or just assume people have commited the
generated docs? ... we can make the nightly build run forrest if it
doesn't already), and we could always include XSLT declarations in the XML
file so that peopel viewing it in a relatively modern browser would see it
as pretty HTML (which could have the same CSS/collapse type functionality
you describe)
not that i'm particularly fond of this status.xml fomat ... i'm just
throwing these ideas out there. Any well structured XML/XHTML format
would let us generate all sorts of views on the changelog using
stylesheets, the forrest version just has the nice bonus of integrating
well with our other documentation (in terms of left nav and style and what
not)
-Hoss
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: formatable changes log
Posted by Doron Cohen <cd...@gmail.com>.
On Jan 26, 2008 2:28 AM, Doron Cohen <cd...@gmail.com> wrote:
> and with a very long file the ability to fold sections is missing
>
Actually the pdf version gives folding and so easier navigation.
Re: formatable changes log
Posted by Doron Cohen <cd...@gmail.com>.
On Jan 25, 2008 1:28 PM, Doron Cohen <cd...@gmail.com> wrote:
> I'll check it, thanks Michael.
>
> On Jan 25, 2008 3:03 AM, Michael Busch <bu...@gmail.com> wrote:
>
> > Forrest has a plugin called projectInfo that can generate a list of
> > changes and an RSS feed from a status.xml file:
> >
> >
> > http://forrest.apache.org/pluginDocs/plugins_0_80/org.apache.forrest.plugin.input.projectInfo/index.html
> >
> > Maybe we should use that?
> >
> > -Michael
> >
>
I checked this plugin - it is nice and powerful alright.
But also IMHO somewhat cumbersome to use:
- Need to define all developers/committers in front and assign each an ID,
and use this ID when referring to them. I guess we can ignore this practice
and just continue to put text - i.e.either (Person1) or (Person1 via
Person2). And BTW, AFAICT for now it does not support that P1 via P2 concept
(though that can be requested as a new feature).
- Need to run forrest in order to see the result. It would then create both
PDF and HTML files (per our settings).
The status.xml that needs to be maintained can be reviewed in
http://people.apache.org/~doronc/status.xml - only two issues there now, but
one can get the picture what it would take to maintain this file.
The result of this file can reviewed in
http://people.apache.org/~doronc/site/ - see the new "Changes" link below
"Overview". It is very rich, though I think there is less flexibility in
formatting the issues, and with a very long file the ability to fold
sections is missing (there might be an option for that too that I didn't
find, or it may be requested...)
To me the main disadvantage of using this is the need to run forrest with
every commit to review the updated changes.html/pdf which I think is almost
too much. Personally I am not very fond of editing XML files, but perhaps
others are. (Editing the html file is not as simple as editing the txt file,
but still I think way simpler than the XML.)
So my preference so far is the HTML version, with a stylesheet(s).
What do others think about this?
Re: formatable changes log
Posted by Doron Cohen <cd...@gmail.com>.
I'll check it, thanks Michael.
On Jan 25, 2008 3:03 AM, Michael Busch <bu...@gmail.com> wrote:
> Forrest has a plugin called projectInfo that can generate a list of
> changes and an RSS feed from a status.xml file:
>
>
> http://forrest.apache.org/pluginDocs/plugins_0_80/org.apache.forrest.plugin.input.projectInfo/index.html
>
> Maybe we should use that?
>
> -Michael
>
> Doron Cohen wrote:
> > As it is becoming hard to browse/navigate CHANGES.txt, how about
> maintaining
> > it in a simple HTML file?
> >
> > Requirements are:
> > - fancier formatting where adequate.
> > - collapse/expand by release/subject
> > - easy to maintain...
> >
> > Here is an example, containing the current (new) trunk and 2.3.0 -
> > http://people.apache.org/~doronc/Changes.html<http://people.apache.org/%7Edoronc/Changes.html>
> >
> > If people like it I will proceed with the rest of the content.
> > If not - other suggestions?
> >
> > - Doron
> >
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: java-dev-help@lucene.apache.org
>
>
Re: formatable changes log
Posted by Michael Busch <bu...@gmail.com>.
Forrest has a plugin called projectInfo that can generate a list of
changes and an RSS feed from a status.xml file:
http://forrest.apache.org/pluginDocs/plugins_0_80/org.apache.forrest.plugin.input.projectInfo/index.html
Maybe we should use that?
-Michael
Doron Cohen wrote:
> As it is becoming hard to browse/navigate CHANGES.txt, how about maintaining
> it in a simple HTML file?
>
> Requirements are:
> - fancier formatting where adequate.
> - collapse/expand by release/subject
> - easy to maintain...
>
> Here is an example, containing the current (new) trunk and 2.3.0 -
> http://people.apache.org/~doronc/Changes.html
>
> If people like it I will proceed with the rest of the content.
> If not - other suggestions?
>
> - Doron
>
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: formatable changes log
Posted by Doron Cohen <cd...@gmail.com>.
On Jan 25, 2008 9:05 PM, Chris Hostetter <ho...@fucit.org> wrote:
>
> : As it is becoming hard to browse/navigate CHANGES.txt, how about
> maintaining
> : it in a simple HTML file?
>
> personally, i'm a fan of simple, plain text files for the CHANGES.txt ...
> easy to edit, easy to read.
I agree with easy to edit, somewhat less with easy to read/understand..:-)
that said: if people want to start using a more structured changelog file
> (xml/html/whatever) i've got no problem with that ... as long as we have a
> stylesheet that can render it as plaintext.
+1
(even better in my mind would be if we could keep editing in plain text,
> and had some handy scripts to reformat into HTML .. but that's obviously a
> little harder to get perfect and probably not worth the effort.)
>
> The other thing to keep in mind if we're going to start discussing new
> ways to manage change logs is that Jira has automated changelog / release
> notes generation built into it, using the issue summaires...
>
>
> http://issues.apache.org/jira/browse/LUCENE?report=com.atlassian.jira.plugin.system.project:changelog-panel
>
> http://issues.apache.org/jira/secure/ConfigureReleaseNote.jspa?projectId=12310110
>
...allthough it's not quite as verbose as our current release notes.
Yes, Changes.txt is definitely needed, more informative.
Re: formatable changes log
Posted by Erik Hatcher <er...@ehatchersolutions.com>.
I switched to maintaining the CHANGES file in YAML format for the
solr-ruby library:
<http://svn.apache.org/repos/asf/lucene/solr/trunk/client/ruby/solr-
ruby/CHANGES.yml>
There is even a unit test to make sure it at least parses properly:
<http://svn.apache.org/repos/asf/lucene/solr/trunk/client/ruby/solr-
ruby/test/unit/changes_yaml_test.rb>
This makes it easily machine processable and also is nicely readable,
thanks to YAML's much-more-pleasant-than-XML nature.
Erik
On Jan 25, 2008, at 2:05 PM, Chris Hostetter wrote:
>
> : As it is becoming hard to browse/navigate CHANGES.txt, how about
> maintaining
> : it in a simple HTML file?
>
> personally, i'm a fan of simple, plain text files for the
> CHANGES.txt ...
> easy to edit, easy to read.
>
> that said: if people want to start using a more structured
> changelog file
> (xml/html/whatever) i've got no problem with that ... as long as we
> have a
> stylesheet that can render it as plaintext.
>
> (even better in my mind would be if we could keep editing in plain
> text,
> and had some handy scripts to reformat into HTML .. but that's
> obviously a
> little harder to get perfect and probably not worth the effort.)
>
> The other thing to keep in mind if we're going to start discussing new
> ways to manage change logs is that Jira has automated changelog /
> release
> notes generation built into it, using the issue summaires...
>
> http://issues.apache.org/jira/browse/LUCENE?
> report=com.atlassian.jira.plugin.system.project:changelog-panel
> http://issues.apache.org/jira/secure/ConfigureReleaseNote.jspa?
> projectId=12310110
>
> ...allthough it's not quite as verbose as our current release notes.
>
>
> -Hoss
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: java-dev-help@lucene.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: formatable changes log
Posted by Doron Cohen <cd...@gmail.com>.
On Jan 26, 2008 6:36 AM, Steven A Rowe <sa...@syr.edu> wrote:
> On 01/25/2008 at 2:05 PM, Chris Hostetter wrote:
> > > As it is becoming hard to browse/navigate CHANGES.txt, how about
> > > maintaining it in a simple HTML file?
> >
> > personally, i'm a fan of simple, plain text files for the
> > CHANGES.txt ... easy to edit, easy to read.
>
> I don't know about easy to read (more than one page per section makes it
> hard to know where you are), but easy to edit, sure.
>
> > (even better in my mind would be if we could keep editing in
> > plain text, and had some handy scripts to reformat into HTML
>
> I was thinking the same thing, and I've done just that, stealing the
> folding Javascript verbatim from Doron's original:
>
> <http://web.syr.edu/~sarowe/Changes.html<http://web.syr.edu/%7Esarowe/Changes.html>
> >
Thanks Steven, this is great!
I added in auto-linkification of JIRA and Bugzilla issues. IMHO, working
> links to issues is the killer feature for an HTML version of CHANGES.txt.
+1
> Here's the Perl script I wrote to produce the above:
>
> <http://web.syr.edu/~sarowe/changes.txt.to.html.pl.txt<http://web.syr.edu/%7Esarowe/changes.txt.to.html.pl.txt>
> >
>
> However, I noticed a problem: in CHANGES.txt under the 2.3.0 release in
> the "Bug fixes" section, there is a gap in the sequence:
>
> 17. LUCENE-1010: Fixed corruption case when document with no term
> vector fields is added after documents with term vector fields.
> This case is hit during merge and would cause an EOFException.
> This bug was introduced with LUCENE-984. (Andi Vajda via Mike
> McCandless)
19. LUCENE-1009: Fix merge slowdown with LogByteSizeMergePolicy when
> autoCommit=false and documents are using stored fields and/or term
> vectors. (Mark Miller via Mike McCandless)
>
> But my script only notices that it's a numbered list, not the specific
> numbers on each item, and so re-numbers item #19 as #18, and then continues
> for all following items to be misaligned with CHANGES.txt. Should we
> preserve incorrect sequencing in the HTML format?
>
I agree with MIke that we should let the script do the numbering.
I created https://issues.apache.org/jira/browse/LUCENE-1157 for this.
>
> On 01/25/2008 at 7:01 AM, DM Smith wrote:
> > And it will solve a charset problem I'm seeing in the file.
> >
> > Under Testing for 2.3.0, there is an accented character that
> > looks like it is encoded in UTF-8 but it is coming across as
> > multi-character.
>
> I added a <META> tag in the <head> tag to set the charset to UTF-8; looks
> like it did the trick.
>
> Steve
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: java-dev-help@lucene.apache.org
>
>
Re: formatable changes log
Posted by Grant Ingersoll <gs...@apache.org>.
On Jan 26, 2008, at 5:05 AM, Michael McCandless wrote:
>
> Steven A Rowe wrote:
>
>> However, I noticed a problem: in CHANGES.txt under the 2.3.0
>> release in the "Bug fixes" section, there is a gap in the sequence:
>
> Argh! Yet more evidence that I cannot count :) This is the 2nd
> time I've done that!
We don't care if you can count, as long as you keep producing
improvements like you have :-)
-Grant
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: formatable changes log
Posted by Michael McCandless <lu...@mikemccandless.com>.
Steven A Rowe wrote:
> However, I noticed a problem: in CHANGES.txt under the 2.3.0
> release in the "Bug fixes" section, there is a gap in the sequence:
Argh! Yet more evidence that I cannot count :) This is the 2nd time
I've done that!
> But my script only notices that it's a numbered list, not the
> specific numbers on each item, and so re-numbers item #19 as #18,
> and then continues for all following items to be misaligned with
> CHANGES.txt. Should we preserve incorrect sequencing in the HTML
> format?
I think, ideally, the script should be the only thing that does the
numbering ;) Then I can't make this mistake again.
So if we can simply put entries like this into CHANGES.txt, under the
right section:
LUCENE-1010: Fixed corruption case when document with no term
vector fields is added after documents with term vector fields.
This case is hit during merge and would cause an EOFException.
This bug was introduced with LUCENE-984. (Andi Vajda via Mike
McCandless)
LUCENE-1009: Fix merge slowdown with LogByteSizeMergePolicy when
autoCommit=false and documents are using stored fields and/or term
vectors. (Mark Miller via Mike McCandless)
And then let the script take care of the numbering, that'd be great!
Mike
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
RE: formatable changes log
Posted by Steven A Rowe <sa...@syr.edu>.
On 01/26/2008 at 3:00 PM, Steven A Rowe wrote:
> On 01/26/2008 at 2:26 PM, Doron Cohen wrote:
> > On Jan 26, 2008 6:32 PM, Steven A Rowe <sa...@syr.edu> wrote:
> > > On 01/26/2008 at 8:07 AM, Grant Ingersoll wrote:
> > > > On Jan 25, 2008, at 11:36 PM, Steven A Rowe wrote:
> > > > > Here's the Perl script I wrote to produce the above:
> > > > >
> > > > > <http://web.syr.edu/~sarowe/changes.txt.to.html.pl.txt>
> > > >
> > > > If we choose this, can you donate it?
> > >
> > > Yes, I can donate it. I put the ASL2 declaration in a comment at the
> > > top of the script.
> >
> > Can you attach it in
> > https://issues.apache.org/jira/browse/LUCENE-1157? -
> > current patch contains your (great) script but to use it
> > 'playing safe' to my understanding your script must be
> > attached by you...
[...]
> I'll merge my changes with yours and make a new patch, which
> I'll attach to the issue a little later today.
Done. See http://web.syr.edu/~sarowe/Changes2.html for the version of Changes.html that I included in the take2 patch.
Steve
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
RE: formatable changes log
Posted by Steven A Rowe <sa...@syr.edu>.
Hi Doron,
On 01/26/2008 at 2:26 PM, Doron Cohen wrote:
> On Jan 26, 2008 6:32 PM, Steven A Rowe <sa...@syr.edu> wrote:
> > On 01/26/2008 at 8:07 AM, Grant Ingersoll wrote:
> > > On Jan 25, 2008, at 11:36 PM, Steven A Rowe wrote:
> > > > Here's the Perl script I wrote to produce the above:
> > > >
> > > > <http://web.syr.edu/~sarowe/changes.txt.to.html.pl.txt>
> > >
> > > If we choose this, can you donate it?
> >
> > Yes, I can donate it. I put the ASL2 declaration in a comment at the
> > top of the script.
>
> Can you attach it in
> https://issues.apache.org/jira/browse/LUCENE-1157? -
> current patch contains your (great) script but to use it
> 'playing safe' to my understanding your script must be
> attached by you...
Sure, actually, I made a couple of modifications to the script:
- added links to JIRA versions of Bugzilla bugs;
- converted most lists to be numbered instead of bulleted, in
preparation for the new non-numbered CHANGES.txt style; and
- some code cleanup: moved large variable definitions to
subroutines at the bottom of the script
I'll merge my changes with yours and make a new patch, which I'll attach to the issue a little later today.
> See http://people.apache.org/~doronc/changes2/Changes.html
Looks great! Thanks for pushing this through, Doron.
Steve
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: formatable changes log
Posted by Doron Cohen <cd...@gmail.com>.
On Jan 26, 2008 6:32 PM, Steven A Rowe <sa...@syr.edu> wrote:
> On 01/26/2008 at 8:07 AM, Grant Ingersoll wrote:
> > On Jan 25, 2008, at 11:36 PM, Steven A Rowe wrote:
> > > Here's the Perl script I wrote to produce the above:
> > >
> > > <http://web.syr.edu/~sarowe/changes.txt.to.html.pl.txt<http://web.syr.edu/%7Esarowe/changes.txt.to.html.pl.txt>
> >
> >
> > If we choose this, can you donate it?
>
> Yes, I can donate it. I put the ASL2 declaration in a comment at the top
> of the script.
>
Can you attach it in https://issues.apache.org/jira/browse/LUCENE-1157? -
current patch contains your (great) script but to use it 'playing safe' to
my understanding your script must be attached by you...
Thanks,
Doron
Re: formatable changes log
Posted by Grant Ingersoll <gs...@apache.org>.
On Jan 26, 2008, at 11:32 AM, Steven A Rowe wrote:
> On 01/26/2008 at 8:07 AM, Grant Ingersoll wrote:
>> On Jan 25, 2008, at 11:36 PM, Steven A Rowe wrote:
>>> Here's the Perl script I wrote to produce the above:
>>>
>>> <http://web.syr.edu/~sarowe/changes.txt.to.html.pl.txt>
>>
>> If we choose this, can you donate it?
>
> Yes, I can donate it. I put the ASL2 declaration in a comment at
> the top of the script.
>
>> We probably need to have it add a license to the top, too.
>
> Do you mean that the output HTML should have a license in it? If
> so, why? The current .txt format doesn't have that...
Good point. I wonder if it should...
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
RE: formatable changes log
Posted by Steven A Rowe <sa...@syr.edu>.
On 01/26/2008 at 8:07 AM, Grant Ingersoll wrote:
> On Jan 25, 2008, at 11:36 PM, Steven A Rowe wrote:
> > Here's the Perl script I wrote to produce the above:
> >
> > <http://web.syr.edu/~sarowe/changes.txt.to.html.pl.txt>
>
> If we choose this, can you donate it?
Yes, I can donate it. I put the ASL2 declaration in a comment at the top of the script.
> We probably need to have it add a license to the top, too.
Do you mean that the output HTML should have a license in it? If so, why? The current .txt format doesn't have that...
Steve
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: formatable changes log
Posted by Grant Ingersoll <gs...@apache.org>.
On Jan 25, 2008, at 11:36 PM, Steven A Rowe wrote:
> On 01/25/2008 at 2:05 PM, Chris Hostetter wrote:
>>> As it is becoming hard to browse/navigate CHANGES.txt, how about
>>> maintaining it in a simple HTML file?
>>
>> personally, i'm a fan of simple, plain text files for the
>> CHANGES.txt ... easy to edit, easy to read.
>
> I don't know about easy to read (more than one page per section
> makes it hard to know where you are), but easy to edit, sure.
>
>> (even better in my mind would be if we could keep editing in
>> plain text, and had some handy scripts to reformat into HTML
>
> I was thinking the same thing, and I've done just that, stealing the
> folding Javascript verbatim from Doron's original:
>
> <http://web.syr.edu/~sarowe/Changes.html>
+1 Great job Steve!
>
>
> I added in auto-linkification of JIRA and Bugzilla issues. IMHO,
> working links to issues is the killer feature for an HTML version of
> CHANGES.txt.
>
> Here's the Perl script I wrote to produce the above:
>
> <http://web.syr.edu/~sarowe/changes.txt.to.html.pl.txt>
If we choose this, can you donate it? I assume everyone knows how to
run perl... We probably should add a target to the build that takes
care of building the site and creating the HTML.
We probably need to have it add a license to the top, too.
-Grant
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
RE: formatable changes log
Posted by Steven A Rowe <sa...@syr.edu>.
On 01/25/2008 at 2:05 PM, Chris Hostetter wrote:
> > As it is becoming hard to browse/navigate CHANGES.txt, how about
> > maintaining it in a simple HTML file?
>
> personally, i'm a fan of simple, plain text files for the
> CHANGES.txt ... easy to edit, easy to read.
I don't know about easy to read (more than one page per section makes it hard to know where you are), but easy to edit, sure.
> (even better in my mind would be if we could keep editing in
> plain text, and had some handy scripts to reformat into HTML
I was thinking the same thing, and I've done just that, stealing the folding Javascript verbatim from Doron's original:
<http://web.syr.edu/~sarowe/Changes.html>
I added in auto-linkification of JIRA and Bugzilla issues. IMHO, working links to issues is the killer feature for an HTML version of CHANGES.txt.
Here's the Perl script I wrote to produce the above:
<http://web.syr.edu/~sarowe/changes.txt.to.html.pl.txt>
However, I noticed a problem: in CHANGES.txt under the 2.3.0 release in the "Bug fixes" section, there is a gap in the sequence:
17. LUCENE-1010: Fixed corruption case when document with no term
vector fields is added after documents with term vector fields.
This case is hit during merge and would cause an EOFException.
This bug was introduced with LUCENE-984. (Andi Vajda via Mike
McCandless)
19. LUCENE-1009: Fix merge slowdown with LogByteSizeMergePolicy when
autoCommit=false and documents are using stored fields and/or term
vectors. (Mark Miller via Mike McCandless)
But my script only notices that it's a numbered list, not the specific numbers on each item, and so re-numbers item #19 as #18, and then continues for all following items to be misaligned with CHANGES.txt. Should we preserve incorrect sequencing in the HTML format?
On 01/25/2008 at 7:01 AM, DM Smith wrote:
> And it will solve a charset problem I'm seeing in the file.
>
> Under Testing for 2.3.0, there is an accented character that
> looks like it is encoded in UTF-8 but it is coming across as
> multi-character.
I added a <META> tag in the <head> tag to set the charset to UTF-8; looks like it did the trick.
Steve
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: formatable changes log
Posted by Chris Hostetter <ho...@fucit.org>.
: As it is becoming hard to browse/navigate CHANGES.txt, how about maintaining
: it in a simple HTML file?
personally, i'm a fan of simple, plain text files for the CHANGES.txt ...
easy to edit, easy to read.
that said: if people want to start using a more structured changelog file
(xml/html/whatever) i've got no problem with that ... as long as we have a
stylesheet that can render it as plaintext.
(even better in my mind would be if we could keep editing in plain text,
and had some handy scripts to reformat into HTML .. but that's obviously a
little harder to get perfect and probably not worth the effort.)
The other thing to keep in mind if we're going to start discussing new
ways to manage change logs is that Jira has automated changelog / release
notes generation built into it, using the issue summaires...
http://issues.apache.org/jira/browse/LUCENE?report=com.atlassian.jira.plugin.system.project:changelog-panel
http://issues.apache.org/jira/secure/ConfigureReleaseNote.jspa?projectId=12310110
...allthough it's not quite as verbose as our current release notes.
-Hoss
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: formatable changes log
Posted by Michael McCandless <lu...@mikemccandless.com>.
+1
I think readability/visibility of the CHANGES, both in CHANGES.txt
and also in release announcements, news items, is important for
"enticing" people to upgrade...
Mike
Doron Cohen wrote:
> As it is becoming hard to browse/navigate CHANGES.txt, how about
> maintaining
> it in a simple HTML file?
>
> Requirements are:
> - fancier formatting where adequate.
> - collapse/expand by release/subject
> - easy to maintain...
>
> Here is an example, containing the current (new) trunk and 2.3.0 -
> http://people.apache.org/~doronc/Changes.html
>
> If people like it I will proceed with the rest of the content.
> If not - other suggestions?
>
> - Doron
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org