You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@maven.apache.org by Brett Porter <br...@apache.org> on 2009/07/10 07:48:26 UTC

Suggested change to site / release

Hi,

I've committed some changes that I'd like reviewed to go forward with  
which makes Maven releases easier.

1) see http://maven.apache.org/docs/2.0.11-RC1-SNAPSHOT/release-notes.html 
  (may not be present yet due to proxying), and relevant commits in  
that RC branch

2) see commits in site branch.

The basic approach is this:

* push all release notes into docs/$version/release-notes.html instead  
of the consolidated older format and add a page to list them in order

* move the release notes for all future versions of Maven into the  
Maven tree itself. This means that you can create/edit them as they  
are a snapshot without messing up the site, and publish them  
automatically with the release.

* set the release up to publish the above site and javadoc/xref at  
release perform time (this is before the vote, but as it is versioned  
it is not going to be live)

* consolidate all version specification for the main site in pom.xml,  
so only those properties need to be edited (I removed 2.1.x, so we  
have the currentStableVersion - 2.2.0, current20xVersion - 2.0.10, and  
a list of all releases for generating the previous release notes, +  
corresponding dates for the current releases)

* remove use of symlink for "current" and instead filter those  
properties into .htaccess

This means that to do a release, assuming it works (which I'll test  
with 2.0.11), it's only the release:prepare / perform cycle + upload  
binaries to www.apache.org (to be automated) + site/pom.xml edit and  
site-deploy.

The downside of the separate site approach is that the release notes  
drop the main navigation (but there is a "Documentation" link back to  
the main site). I don't think this is a bad thing.

Any objections to continuing this approach with Maven 2.2.x, and  
perhaps making similar attempts on the plugins?

Cheers,
Brett



---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org


Re: Suggested change to site / release

Posted by Paul Benedict <pb...@apache.org>.
+1 on keeping all the release notes online!!

On Sun, Jul 19, 2009 at 8:07 AM, Jason van Zyl<jv...@sonatype.com> wrote:
> Just getting back after being sick for a week.
>
> On 10-Jul-09, at 7:18 PM, Brett Porter wrote:
>
>> sorry, these changes should have been on a branch. I'll move that across
>> now so that trunk is still deployable. I'm heading out now but I can respond
>> to these issues later.
>>
>
> No biggie. I just think the notes being aggregated to be a good thing.
> Doesn't mean we can't do both if it's still convenient.
>
>> On 11/07/2009, at 12:27 AM, Jason van Zyl wrote:
>>
>>>
>>> On 10-Jul-09, at 1:48 AM, Brett Porter wrote:
>>>
>>>> Hi,
>>>>
>>>> I've committed some changes that I'd like reviewed to go forward with
>>>> which makes Maven releases easier.
>>>>
>>>> 1) see
>>>> http://maven.apache.org/docs/2.0.11-RC1-SNAPSHOT/release-notes.html (may not
>>>> be present yet due to proxying), and relevant commits in that RC branch
>>>>
>>>> 2) see commits in site branch.
>>>>
>>>> The basic approach is this:
>>>>
>>>> * push all release notes into docs/$version/release-notes.html instead
>>>> of the consolidated older format and add a page to list them in order
>>>>
>>>
>>> So if someone wants to see the historical list of changes they will need
>>> to look at N documents? The consolidated format is good as the history of
>>> change is kept in one place which is what people looking to migrate want to
>>> see.
>>>
>>>> * move the release notes for all future versions of Maven into the Maven
>>>> tree itself. This means that you can create/edit them as they are a snapshot
>>>> without messing up the site, and publish them automatically with the
>>>> release.
>>>>
>>>
>>> Again these changes span versions. I have no problem keeping these in SVN
>>> somewhere but chopping up the release notes into multiple documents makes it
>>> really hard to view the high level changes over time. If folks want to see
>>> exacting detail per version they can get this from JIRA. The release notes
>>> should be cohesive spanning multiple versions. They at least need to be in
>>> an aggregated form somewhere.
>>>
>>>> * set the release up to publish the above site and javadoc/xref at
>>>> release perform time (this is before the vote, but as it is versioned it is
>>>> not going to be live)
>>>>
>>>
>>> If you mean coupling the publishing of site during the release then -1.
>>>
>>> The site publishing cannot be coupled to the actual release. The release
>>> of the binaries should not fail because of some aggregation, ordering or
>>> some other problem with the reporting/site system. Whoever is doing the
>>> release can do this in two steps. Some external system could orchestrate
>>> this but the actual release itself should not couple the site publishing the
>>> distribution of binaries.
>>>
>>>> * consolidate all version specification for the main site in pom.xml, so
>>>> only those properties need to be edited (I removed 2.1.x, so we have the
>>>> currentStableVersion - 2.2.0, current20xVersion - 2.0.10, and a list of all
>>>> releases for generating the previous release notes, + corresponding dates
>>>> for the current releases)
>>>>
>>>> * remove use of symlink for "current" and instead filter those
>>>> properties into .htaccess
>>>>
>>>> This means that to do a release, assuming it works (which I'll test with
>>>> 2.0.11), it's only the release:prepare / perform cycle + upload binaries to
>>>> www.apache.org (to be automated) + site/pom.xml edit and site-deploy.
>>>>
>>>> The downside of the separate site approach is that the release notes
>>>> drop the main navigation (but there is a "Documentation" link back to the
>>>> main site). I don't think this is a bad thing.
>>>>
>>>> Any objections to continuing this approach with Maven 2.2.x, and perhaps
>>>> making similar attempts on the plugins?
>>>>
>>>
>>> As bad as the site is now people are accustomed at least to the
>>> structure. I really think you should think hard about wanting to flip all
>>> this around again. The problem on the site is the content, not the
>>> structure. There is actually far too much structure are far too little
>>> meaningful information. I honestly don't think this is the best use of
>>> anyone's time and the focus should be simplification and clarifying the
>>> existing content more then anything.
>>>
>>>> Cheers,
>>>> Brett
>>>>
>>>>
>>>>
>>>> ---------------------------------------------------------------------
>>>> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
>>>> For additional commands, e-mail: dev-help@maven.apache.org
>>>>
>>>
>>> Thanks,
>>>
>>> Jason
>>>
>>> ----------------------------------------------------------
>>> Jason van Zyl
>>> Founder,  Apache Maven
>>> http://twitter.com/jvanzyl
>>> http://twitter.com/SonatypeNexus
>>> http://twitter.com/SonatypeM2E
>>> ----------------------------------------------------------
>>>
>>>
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
>>> For additional commands, e-mail: dev-help@maven.apache.org
>>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
>> For additional commands, e-mail: dev-help@maven.apache.org
>>
>
> Thanks,
>
> Jason
>
> ----------------------------------------------------------
> Jason van Zyl
> Founder,  Apache Maven
> http://twitter.com/jvanzyl
> http://twitter.com/SonatypeNexus
> http://twitter.com/SonatypeM2E
> ----------------------------------------------------------
>
> First, the taking in of scattered particulars under one Idea,
> so that everyone understands what is being talked about ... Second,
> the separation of the Idea into parts, by dividing it at the joints,
> as nature directs, not breaking any limb in half as a bad carver might.
>
>  -- Plato, Phaedrus (Notes on the Synthesis of Form by C. Alexander)
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org


Re: Suggested change to site / release

Posted by Jason van Zyl <jv...@sonatype.com>.
Just getting back after being sick for a week.

On 10-Jul-09, at 7:18 PM, Brett Porter wrote:

> sorry, these changes should have been on a branch. I'll move that  
> across now so that trunk is still deployable. I'm heading out now  
> but I can respond to these issues later.
>

No biggie. I just think the notes being aggregated to be a good thing.  
Doesn't mean we can't do both if it's still convenient.

> On 11/07/2009, at 12:27 AM, Jason van Zyl wrote:
>
>>
>> On 10-Jul-09, at 1:48 AM, Brett Porter wrote:
>>
>>> Hi,
>>>
>>> I've committed some changes that I'd like reviewed to go forward  
>>> with which makes Maven releases easier.
>>>
>>> 1) see http://maven.apache.org/docs/2.0.11-RC1-SNAPSHOT/release-notes.html 
>>>  (may not be present yet due to proxying), and relevant commits in  
>>> that RC branch
>>>
>>> 2) see commits in site branch.
>>>
>>> The basic approach is this:
>>>
>>> * push all release notes into docs/$version/release-notes.html  
>>> instead of the consolidated older format and add a page to list  
>>> them in order
>>>
>>
>> So if someone wants to see the historical list of changes they will  
>> need to look at N documents? The consolidated format is good as the  
>> history of change is kept in one place which is what people looking  
>> to migrate want to see.
>>
>>> * move the release notes for all future versions of Maven into the  
>>> Maven tree itself. This means that you can create/edit them as  
>>> they are a snapshot without messing up the site, and publish them  
>>> automatically with the release.
>>>
>>
>> Again these changes span versions. I have no problem keeping these  
>> in SVN somewhere but chopping up the release notes into multiple  
>> documents makes it really hard to view the high level changes over  
>> time. If folks want to see exacting detail per version they can get  
>> this from JIRA. The release notes should be cohesive spanning  
>> multiple versions. They at least need to be in an aggregated form  
>> somewhere.
>>
>>> * set the release up to publish the above site and javadoc/xref at  
>>> release perform time (this is before the vote, but as it is  
>>> versioned it is not going to be live)
>>>
>>
>> If you mean coupling the publishing of site during the release then  
>> -1.
>>
>> The site publishing cannot be coupled to the actual release. The  
>> release of the binaries should not fail because of some  
>> aggregation, ordering or some other problem with the reporting/site  
>> system. Whoever is doing the release can do this in two steps. Some  
>> external system could orchestrate this but the actual release  
>> itself should not couple the site publishing the distribution of  
>> binaries.
>>
>>> * consolidate all version specification for the main site in  
>>> pom.xml, so only those properties need to be edited (I removed  
>>> 2.1.x, so we have the currentStableVersion - 2.2.0,  
>>> current20xVersion - 2.0.10, and a list of all releases for  
>>> generating the previous release notes, + corresponding dates for  
>>> the current releases)
>>>
>>> * remove use of symlink for "current" and instead filter those  
>>> properties into .htaccess
>>>
>>> This means that to do a release, assuming it works (which I'll  
>>> test with 2.0.11), it's only the release:prepare / perform cycle +  
>>> upload binaries to www.apache.org (to be automated) + site/pom.xml  
>>> edit and site-deploy.
>>>
>>> The downside of the separate site approach is that the release  
>>> notes drop the main navigation (but there is a "Documentation"  
>>> link back to the main site). I don't think this is a bad thing.
>>>
>>> Any objections to continuing this approach with Maven 2.2.x, and  
>>> perhaps making similar attempts on the plugins?
>>>
>>
>> As bad as the site is now people are accustomed at least to the  
>> structure. I really think you should think hard about wanting to  
>> flip all this around again. The problem on the site is the content,  
>> not the structure. There is actually far too much structure are far  
>> too little meaningful information. I honestly don't think this is  
>> the best use of anyone's time and the focus should be  
>> simplification and clarifying the existing content more then  
>> anything.
>>
>>> Cheers,
>>> Brett
>>>
>>>
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
>>> For additional commands, e-mail: dev-help@maven.apache.org
>>>
>>
>> Thanks,
>>
>> Jason
>>
>> ----------------------------------------------------------
>> Jason van Zyl
>> Founder,  Apache Maven
>> http://twitter.com/jvanzyl
>> http://twitter.com/SonatypeNexus
>> http://twitter.com/SonatypeM2E
>> ----------------------------------------------------------
>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
>> For additional commands, e-mail: dev-help@maven.apache.org
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>

Thanks,

Jason

----------------------------------------------------------
Jason van Zyl
Founder,  Apache Maven
http://twitter.com/jvanzyl
http://twitter.com/SonatypeNexus
http://twitter.com/SonatypeM2E
----------------------------------------------------------

First, the taking in of scattered particulars under one Idea,
so that everyone understands what is being talked about ... Second,
the separation of the Idea into parts, by dividing it at the joints,
as nature directs, not breaking any limb in half as a bad carver might.

   -- Plato, Phaedrus (Notes on the Synthesis of Form by C. Alexander)


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org


Re: Suggested change to site / release

Posted by Brett Porter <br...@apache.org>.
sorry, these changes should have been on a branch. I'll move that  
across now so that trunk is still deployable. I'm heading out now but  
I can respond to these issues later.

On 11/07/2009, at 12:27 AM, Jason van Zyl wrote:

>
> On 10-Jul-09, at 1:48 AM, Brett Porter wrote:
>
>> Hi,
>>
>> I've committed some changes that I'd like reviewed to go forward  
>> with which makes Maven releases easier.
>>
>> 1) see http://maven.apache.org/docs/2.0.11-RC1-SNAPSHOT/release-notes.html 
>>  (may not be present yet due to proxying), and relevant commits in  
>> that RC branch
>>
>> 2) see commits in site branch.
>>
>> The basic approach is this:
>>
>> * push all release notes into docs/$version/release-notes.html  
>> instead of the consolidated older format and add a page to list  
>> them in order
>>
>
> So if someone wants to see the historical list of changes they will  
> need to look at N documents? The consolidated format is good as the  
> history of change is kept in one place which is what people looking  
> to migrate want to see.
>
>> * move the release notes for all future versions of Maven into the  
>> Maven tree itself. This means that you can create/edit them as they  
>> are a snapshot without messing up the site, and publish them  
>> automatically with the release.
>>
>
> Again these changes span versions. I have no problem keeping these  
> in SVN somewhere but chopping up the release notes into multiple  
> documents makes it really hard to view the high level changes over  
> time. If folks want to see exacting detail per version they can get  
> this from JIRA. The release notes should be cohesive spanning  
> multiple versions. They at least need to be in an aggregated form  
> somewhere.
>
>> * set the release up to publish the above site and javadoc/xref at  
>> release perform time (this is before the vote, but as it is  
>> versioned it is not going to be live)
>>
>
> If you mean coupling the publishing of site during the release then  
> -1.
>
> The site publishing cannot be coupled to the actual release. The  
> release of the binaries should not fail because of some aggregation,  
> ordering or some other problem with the reporting/site system.  
> Whoever is doing the release can do this in two steps. Some external  
> system could orchestrate this but the actual release itself should  
> not couple the site publishing the distribution of binaries.
>
>> * consolidate all version specification for the main site in  
>> pom.xml, so only those properties need to be edited (I removed  
>> 2.1.x, so we have the currentStableVersion - 2.2.0,  
>> current20xVersion - 2.0.10, and a list of all releases for  
>> generating the previous release notes, + corresponding dates for  
>> the current releases)
>>
>> * remove use of symlink for "current" and instead filter those  
>> properties into .htaccess
>>
>> This means that to do a release, assuming it works (which I'll test  
>> with 2.0.11), it's only the release:prepare / perform cycle +  
>> upload binaries to www.apache.org (to be automated) + site/pom.xml  
>> edit and site-deploy.
>>
>> The downside of the separate site approach is that the release  
>> notes drop the main navigation (but there is a "Documentation" link  
>> back to the main site). I don't think this is a bad thing.
>>
>> Any objections to continuing this approach with Maven 2.2.x, and  
>> perhaps making similar attempts on the plugins?
>>
>
> As bad as the site is now people are accustomed at least to the  
> structure. I really think you should think hard about wanting to  
> flip all this around again. The problem on the site is the content,  
> not the structure. There is actually far too much structure are far  
> too little meaningful information. I honestly don't think this is  
> the best use of anyone's time and the focus should be simplification  
> and clarifying the existing content more then anything.
>
>> Cheers,
>> Brett
>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
>> For additional commands, e-mail: dev-help@maven.apache.org
>>
>
> Thanks,
>
> Jason
>
> ----------------------------------------------------------
> Jason van Zyl
> Founder,  Apache Maven
> http://twitter.com/jvanzyl
> http://twitter.com/SonatypeNexus
> http://twitter.com/SonatypeM2E
> ----------------------------------------------------------
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org


Re: Suggested change to site / release

Posted by Brett Porter <br...@apache.org>.
On 11/07/2009, at 12:27 AM, Jason van Zyl wrote:

>> * push all release notes into docs/$version/release-notes.html  
>> instead of the consolidated older format and add a page to list  
>> them in order
>>
>
> So if someone wants to see the historical list of changes they will  
> need to look at N documents? The consolidated format is good as the  
> history of change is kept in one place which is what people looking  
> to migrate want to see.

Actually, yeah, I'm more in favour of accumulated notes for the same  
reasons Jesse pointed out (though still deploying separate versions  
that grow, and maybe starting to trim back over time if appropriate).  
Would that make sense?

>
>> * set the release up to publish the above site and javadoc/xref at  
>> release perform time (this is before the vote, but as it is  
>> versioned it is not going to be live)
>>
>
> If you mean coupling the publishing of site during the release then  
> -1.
>
> The site publishing cannot be coupled to the actual release. The  
> release of the binaries should not fail because of some aggregation,  
> ordering or some other problem with the reporting/site system.  
> Whoever is doing the release can do this in two steps. Some external  
> system could orchestrate this but the actual release itself should  
> not couple the site publishing the distribution of binaries.

I'm not sure why this is an issue - it's only a small sensible subset  
of the site (javadocs and source xref). The problem at the moment is  
that even though its in the release instructions it tends to get  
skipped because only release:prepare/perform is remembered. If it can  
be bundled in there (but disabled if desired), doesn't it make sense  
to do in one hit?

>>
>> The downside of the separate site approach is that the release  
>> notes drop the main navigation (but there is a "Documentation" link  
>> back to the main site). I don't think this is a bad thing.
>>
>> Any objections to continuing this approach with Maven 2.2.x, and  
>> perhaps making similar attempts on the plugins?
>>
>
> As bad as the site is now people are accustomed at least to the  
> structure. I really think you should think hard about wanting to  
> flip all this around again. The problem on the site is the content,  
> not the structure. There is actually far too much structure are far  
> too little meaningful information. I honestly don't think this is  
> the best use of anyone's time and the focus should be simplification  
> and clarifying the existing content more then anything.

I don't think my purpose was clear - this is about removing the  
fiddling with release notes and versions on the site when a release is  
done, which has required quite a bit of clean up after the last couple  
of releases. As John said, there's too many moving parts, so this was  
partially an attempt to automate as much as possible, and structure it  
so further automation (like updating the release notes from jira at  
release time) could make sense. I'm not trying to change the  
documentation structure at this stage. Though I do think versioning it  
makes sense, you're completely correct that the first focus needs to  
be on content if work is done there.

Cheers,
Brett

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org


Re: Suggested change to site / release

Posted by Brett Porter <br...@apache.org>.
Thanks,t hat might be worth a try

On 13/07/2009, at 9:34 AM, Barrie Treloar wrote:

> On Sat, Jul 11, 2009 at 2:00 AM, Brian Fox<br...@infinity.nu> wrote:
>> I think jira should remain the consolidated list of bugs fixed during
>> a release. Having it on the site is important, but specifically I
>> don't want to have yet another file to update each time i fix a bug.
>> Grabbing the release notes from jira and updating the site is nice  
>> and
>> efficient and pretty error proof.
>
> apt snippet and a template file to pull everything together may get
> you both the individual files and the aggregate files.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org


Re: Suggested change to site / release

Posted by Barrie Treloar <ba...@gmail.com>.
On Sat, Jul 11, 2009 at 2:00 AM, Brian Fox<br...@infinity.nu> wrote:
> I think jira should remain the consolidated list of bugs fixed during
> a release. Having it on the site is important, but specifically I
> don't want to have yet another file to update each time i fix a bug.
> Grabbing the release notes from jira and updating the site is nice and
> efficient and pretty error proof.

apt snippet and a template file to pull everything together may get
you both the individual files and the aggregate files.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org


Re: Suggested change to site / release

Posted by Brian Fox <br...@infinity.nu>.
I think jira should remain the consolidated list of bugs fixed during
a release. Having it on the site is important, but specifically I
don't want to have yet another file to update each time i fix a bug.
Grabbing the release notes from jira and updating the site is nice and
efficient and pretty error proof.

On Fri, Jul 10, 2009 at 11:34 AM, Jesse
McConnell<je...@gmail.com> wrote:
>>> 2) see commits in site branch.
>>>
>>> The basic approach is this:
>>>
>>> * push all release notes into docs/$version/release-notes.html instead of
>>> the consolidated older format and add a page to list them in order
>>>
>>
>> So if someone wants to see the historical list of changes they will need to
>> look at N documents? The consolidated format is good as the history of
>> change is kept in one place which is what people looking to migrate want to
>> see.
>
> we struggle with this for jetty as well...historically we have a
> VERSIONS.txt file in the root of the project that is incrementally
> updated with each resolves bugzilla or jira issue.  I don't think we
> would want to split this up on a per release basis as it allows folks
> who are upgrading from a few versions behind one location to look to
> see all of the resolves issues since their version.
>
> managing that consolidated file is a pain though as it seems silly to
> pass it around as a resource inside of an assembly to broker it around
> the build and the top of the build is the best place to keep the
> file...
>
> anyway, doesn't strictly apply but I agree with jason on the value of
> a consolidated release notes file
>
> cheers,
> jesse
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org


Re: Suggested change to site / release

Posted by Jesse McConnell <je...@gmail.com>.
>> 2) see commits in site branch.
>>
>> The basic approach is this:
>>
>> * push all release notes into docs/$version/release-notes.html instead of
>> the consolidated older format and add a page to list them in order
>>
>
> So if someone wants to see the historical list of changes they will need to
> look at N documents? The consolidated format is good as the history of
> change is kept in one place which is what people looking to migrate want to
> see.

we struggle with this for jetty as well...historically we have a
VERSIONS.txt file in the root of the project that is incrementally
updated with each resolves bugzilla or jira issue.  I don't think we
would want to split this up on a per release basis as it allows folks
who are upgrading from a few versions behind one location to look to
see all of the resolves issues since their version.

managing that consolidated file is a pain though as it seems silly to
pass it around as a resource inside of an assembly to broker it around
the build and the top of the build is the best place to keep the
file...

anyway, doesn't strictly apply but I agree with jason on the value of
a consolidated release notes file

cheers,
jesse

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org


Re: Suggested change to site / release

Posted by Jason van Zyl <jv...@sonatype.com>.
On 10-Jul-09, at 1:48 AM, Brett Porter wrote:

> Hi,
>
> I've committed some changes that I'd like reviewed to go forward  
> with which makes Maven releases easier.
>
> 1) see http://maven.apache.org/docs/2.0.11-RC1-SNAPSHOT/release-notes.html 
>  (may not be present yet due to proxying), and relevant commits in  
> that RC branch
>
> 2) see commits in site branch.
>
> The basic approach is this:
>
> * push all release notes into docs/$version/release-notes.html  
> instead of the consolidated older format and add a page to list them  
> in order
>

So if someone wants to see the historical list of changes they will  
need to look at N documents? The consolidated format is good as the  
history of change is kept in one place which is what people looking to  
migrate want to see.

> * move the release notes for all future versions of Maven into the  
> Maven tree itself. This means that you can create/edit them as they  
> are a snapshot without messing up the site, and publish them  
> automatically with the release.
>

Again these changes span versions. I have no problem keeping these in  
SVN somewhere but chopping up the release notes into multiple  
documents makes it really hard to view the high level changes over  
time. If folks want to see exacting detail per version they can get  
this from JIRA. The release notes should be cohesive spanning multiple  
versions. They at least need to be in an aggregated form somewhere.

> * set the release up to publish the above site and javadoc/xref at  
> release perform time (this is before the vote, but as it is  
> versioned it is not going to be live)
>

If you mean coupling the publishing of site during the release then -1.

The site publishing cannot be coupled to the actual release. The  
release of the binaries should not fail because of some aggregation,  
ordering or some other problem with the reporting/site system. Whoever  
is doing the release can do this in two steps. Some external system  
could orchestrate this but the actual release itself should not couple  
the site publishing the distribution of binaries.

> * consolidate all version specification for the main site in  
> pom.xml, so only those properties need to be edited (I removed  
> 2.1.x, so we have the currentStableVersion - 2.2.0,  
> current20xVersion - 2.0.10, and a list of all releases for  
> generating the previous release notes, + corresponding dates for the  
> current releases)
>
> * remove use of symlink for "current" and instead filter those  
> properties into .htaccess
>
> This means that to do a release, assuming it works (which I'll test  
> with 2.0.11), it's only the release:prepare / perform cycle + upload  
> binaries to www.apache.org (to be automated) + site/pom.xml edit and  
> site-deploy.
>
> The downside of the separate site approach is that the release notes  
> drop the main navigation (but there is a "Documentation" link back  
> to the main site). I don't think this is a bad thing.
>
> Any objections to continuing this approach with Maven 2.2.x, and  
> perhaps making similar attempts on the plugins?
>

As bad as the site is now people are accustomed at least to the  
structure. I really think you should think hard about wanting to flip  
all this around again. The problem on the site is the content, not the  
structure. There is actually far too much structure are far too little  
meaningful information. I honestly don't think this is the best use of  
anyone's time and the focus should be simplification and clarifying  
the existing content more then anything.

> Cheers,
> Brett
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>

Thanks,

Jason

----------------------------------------------------------
Jason van Zyl
Founder,  Apache Maven
http://twitter.com/jvanzyl
http://twitter.com/SonatypeNexus
http://twitter.com/SonatypeM2E
----------------------------------------------------------



---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org


Re: Suggested change to site / release

Posted by Arnaud HERITIER <ah...@gmail.com>.
+1 for all that improve our horrible website.Your proposal is good, giving a
better management of // branches, thus +1
Cheers,

Arnaud

# Arnaud Héritier
# Software Factory Manager
# eXo Platform
# http://www.exoplatform.com
# http://blog.aheritier.net


On Fri, Jul 10, 2009 at 7:48 AM, Brett Porter <br...@apache.org> wrote:

> Hi,
>
> I've committed some changes that I'd like reviewed to go forward with which
> makes Maven releases easier.
>
> 1) see http://maven.apache.org/docs/2.0.11-RC1-SNAPSHOT/release-notes.html (may
> not be present yet due to proxying), and relevant commits in that RC branch
>
> 2) see commits in site branch.
>
> The basic approach is this:
>
> * push all release notes into docs/$version/release-notes.html instead of
> the consolidated older format and add a page to list them in order
>
> * move the release notes for all future versions of Maven into the Maven
> tree itself. This means that you can create/edit them as they are a snapshot
> without messing up the site, and publish them automatically with the
> release.
>
> * set the release up to publish the above site and javadoc/xref at release
> perform time (this is before the vote, but as it is versioned it is not
> going to be live)
>
> * consolidate all version specification for the main site in pom.xml, so
> only those properties need to be edited (I removed 2.1.x, so we have the
> currentStableVersion - 2.2.0, current20xVersion - 2.0.10, and a list of all
> releases for generating the previous release notes, + corresponding dates
> for the current releases)
>
> * remove use of symlink for "current" and instead filter those properties
> into .htaccess
>
> This means that to do a release, assuming it works (which I'll test with
> 2.0.11), it's only the release:prepare / perform cycle + upload binaries to
> www.apache.org (to be automated) + site/pom.xml edit and site-deploy.
>
> The downside of the separate site approach is that the release notes drop
> the main navigation (but there is a "Documentation" link back to the main
> site). I don't think this is a bad thing.
>
> Any objections to continuing this approach with Maven 2.2.x, and perhaps
> making similar attempts on the plugins?
>
> Cheers,
> Brett
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>

Re: Suggested change to site / release

Posted by Emmanuel Venisse <em...@gmail.com>.
+1 for all

Emmanuel

On Fri, Jul 10, 2009 at 7:48 AM, Brett Porter <br...@apache.org> wrote:

> Hi,
>
> I've committed some changes that I'd like reviewed to go forward with which
> makes Maven releases easier.
>
> 1) see http://maven.apache.org/docs/2.0.11-RC1-SNAPSHOT/release-notes.html (may
> not be present yet due to proxying), and relevant commits in that RC branch
>
> 2) see commits in site branch.
>
> The basic approach is this:
>
> * push all release notes into docs/$version/release-notes.html instead of
> the consolidated older format and add a page to list them in order
>
> * move the release notes for all future versions of Maven into the Maven
> tree itself. This means that you can create/edit them as they are a snapshot
> without messing up the site, and publish them automatically with the
> release.
>
> * set the release up to publish the above site and javadoc/xref at release
> perform time (this is before the vote, but as it is versioned it is not
> going to be live)
>
> * consolidate all version specification for the main site in pom.xml, so
> only those properties need to be edited (I removed 2.1.x, so we have the
> currentStableVersion - 2.2.0, current20xVersion - 2.0.10, and a list of all
> releases for generating the previous release notes, + corresponding dates
> for the current releases)
>
> * remove use of symlink for "current" and instead filter those properties
> into .htaccess
>
> This means that to do a release, assuming it works (which I'll test with
> 2.0.11), it's only the release:prepare / perform cycle + upload binaries to
> www.apache.org (to be automated) + site/pom.xml edit and site-deploy.
>
> The downside of the separate site approach is that the release notes drop
> the main navigation (but there is a "Documentation" link back to the main
> site). I don't think this is a bad thing.
>
> Any objections to continuing this approach with Maven 2.2.x, and perhaps
> making similar attempts on the plugins?
>
> Cheers,
> Brett
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>