Documentation is generated from the trunk not from the latest stable release

[Jean-Marc Fontaine]

Documentation on the website is generated from the trunk and not from the latest stable release.

Thus, newly implemented features appear in the documentation but they can't be used with the latest stable release. I lost time twice this week because of this.

The routing by hostname do not work in 1.6.1 the way it is described in the documentation and the "ignore" option of Zend_Translate described in the documentation won't be available before 1.7 release.

Regards,

Jean-Marc

[thomasW]

We are aware of this problems.
But the manual in trunk states that this features are available with 1.7...
so this should not be a big problem at all.

Greetings
Thomas Weidner, I18N Team Leader, Zend Framework
http://www.thomasweidner.com

----- Original Message -----
From: "Jean-Marc Fontaine" <jmf@...>
To: <fw-docs@...>
Sent: Friday, October 10, 2008 9:00 AM
Subject: Documentation is generated from the trunk not from the latest
stable release

>
> Documentation on the website is generated from the trunk and not from the
> latest stable release.
>
> Thus, newly implemented features appear in the documentation but they
> can't
> be used with the latest stable release. I lost time twice this week
> because
> of this.
>
> The routing by hostname do not work in 1.6.1 the way it is described in
> the
> documentation and the "ignore" option of Zend_Translate described in the
> documentation won't be available before 1.7 release.
>
> Regards,
>
> Jean-Marc
> --
> View this message in context:
> http://www.nabble.com/Documentation-is-generated-from-the-trunk-not-from-the-latest-stable-release-tp19912997p19912997.html
> Sent from the Zend Doc mailing list archive at Nabble.com.

[Jean-Marc Fontaine]

Hello Thomas,

thomasW wrote:

But the manual in trunk states that this features are available with 1.7...
so this should not be a big problem at all.

The documentation only mentions 1.7 release once : "Zend_Translate recognises also an application wide locale". There is nothing regarding the "ignore" option.

BTW, this is another problem. I read the whole Zend_Translate documentation last week. I saw "Since Zend Framework 1.7.0". I guessed "It's out !" but no, it isn't.

Having a trunk documentation somewhere is fine but the main documentation should be from the latest stable release IMHO.

Regards,

Jean-Marc

[thomasW]

Your suggestion would mean that we can not add new features in trunk as
every commit must include code, unittests AND documentation.

Leaving out documentation would then mean no new features in trunk.
Is this really what you suggest ?

Greetings
Thomas Weidner, I18N Team Leader, Zend Framework
http://www.thomasweidner.com

----- Original Message -----
From: "Jean-Marc Fontaine" <jmf@...>
To: "Thomas Weidner" <thomas.weidner@...>
Cc: <fw-docs@...>
Sent: Friday, October 10, 2008 10:02 AM
Subject: Re: Documentation is generated from the trunk not from the latest
stable release

> Hello Thomas,
>
>> But the manual in trunk states that this features are available with
>> 1.7... so this should not be a big problem at all.
> The documentation only mentions 1.7 release once : "Zend_Translate
> recognises also an application wide locale". There is nothing regarding
> the "ignore" option.
>
> BTW, this is another problem. I read the whole Zend_Translate
> documentation last week. I saw "Since Zend Framework 1.7.0". I guessed
> "It's out !" but no, it isn't.
>
> Having a trunk documentation somewhere is fine but the main documentation
> should be from the latest stable release IMHO.
>
> Regards,
>
> Jean-Marc
>
> --------------------------------------------
> Kanopée - Développement Informatique Durable
> 57 rue d'Haubourdin
> 59139 Wattignies
>
> Tél      : [phone]
> Portable : 06 88 56 50 79
> Fax      : [phone]
> Web      : http://www.kanopee.net/ 

[weierophinney]

-- Thomas Weidner <thomas.weidner@...> wrote
(on Friday, 10 October 2008, 10:39 AM +0200):
> Your suggestion would mean that we can not add new features in trunk as  
> every commit must include code, unittests AND documentation.
>
> Leaving out documentation would then mean no new features in trunk.
> Is this really what you suggest ?

Thomas -- there is a solution to this: build documentation off the
release branch. However, we need to come up with a strategy for (a)
having versioned documentation on the website, and (b) how and when to
merge documentation changes to the release branch (something that has
never been required before for documentation translators). The internal
team has this on our backlog.

> ----- Original Message ----- From: "Jean-Marc Fontaine" <jmf@...>
> To: "Thomas Weidner" <thomas.weidner@...>
> Cc: <fw-docs@...>
> Sent: Friday, October 10, 2008 10:02 AM
> Subject: Re: Documentation is generated from the trunk not from the
> latest stable release
>
>
>> Hello Thomas,
>>
>>> But the manual in trunk states that this features are available with  
>>> 1.7... so this should not be a big problem at all.
>> The documentation only mentions 1.7 release once : "Zend_Translate  
>> recognises also an application wide locale". There is nothing regarding
>> the "ignore" option.
>>
>> BTW, this is another problem. I read the whole Zend_Translate  
>> documentation last week. I saw "Since Zend Framework 1.7.0". I guessed  
>> "It's out !" but no, it isn't.
>>
>> Having a trunk documentation somewhere is fine but the main
>> documentation should be from the latest stable release IMHO.
>>
>> Regards,
>>
>> Jean-Marc
>>
>> --------------------------------------------
>> Kanopée - Développement Informatique Durable
>> 57 rue d'Haubourdin
>> 59139 Wattignies
>>
>> Tél      : [phone]
>> Portable : 06 88 56 50 79
>> Fax      : [phone]
>> Web      : http://www.kanopee.net/ 
>

--
Matthew Weier O'Phinney
Software Architect       | matthew@...
Zend Framework           | http://framework.zend.com/

[wllm]

We've already discussed how to fix this on the site. What do you people
think would be best? Maybe just making the last production release
available on the site with a clear statement saying what version they
are associated with? If someone is working from trunk, it seems to me
that they will likely also have the doc-fu to build the API docs.

,Wil

> -----Original Message-----
> From: Jean-Marc Fontaine [mailto:jmf@...]
> Sent: Friday, October 10, 2008 12:01 AM
> To: fw-docs@...
> Subject: Documentation is generated from the trunk not from the latest
> stable release
>
>
> Documentation on the website is generated from the trunk and not from
> the
> latest stable release.
>
> Thus, newly implemented features appear in the documentation but they
> can't
> be used with the latest stable release. I lost time twice this week
> because
> of this.
>
> The routing by hostname do not work in 1.6.1 the way it is described

in

> the
> documentation and the "ignore" option of Zend_Translate described in
> the
> documentation won't be available before 1.7 release.
>
> Regards,
>
> Jean-Marc
> --
> View this message in context: http://www.nabble.com/Documentation-is-
> generated-from-the-trunk-not-from-the-latest-stable-release-
> tp19912997p19912997.html
> Sent from the Zend Doc mailing list archive at Nabble.com.

[thomasW]

Wil,

what he've mentioned would still not be covered.
The docu failures he mentioned for I18N were integrated for 1.6 but the
dev-team decided to delay them for 1.7.
So this could still occur in such a case.

The right solution is to have docu also branched.
As new features are only for trunk this should be no problem.
This way we could even provide a docu for the subreleases and a docu for the
nightly snapshot the same time.

Greetings
Thomas Weidner, I18N Team Leader, Zend Framework
http://www.thomasweidner.com

----- Original Message -----
From: "Wil Sinclair" <wil@...>
To: "Jean-Marc Fontaine" <jmf@...>; <fw-docs@...>
Sent: Friday, October 10, 2008 9:54 PM
Subject: RE: Documentation is generated from the trunk not from the latest
stable release


We've already discussed how to fix this on the site. What do you people
think would be best? Maybe just making the last production release
available on the site with a clear statement saying what version they
are associated with? If someone is working from trunk, it seems to me
that they will likely also have the doc-fu to build the API docs.

,Wil

> -----Original Message-----
> From: Jean-Marc Fontaine [mailto:jmf@...]
> Sent: Friday, October 10, 2008 12:01 AM
> To: fw-docs@...
> Subject: Documentation is generated from the trunk not from the latest
> stable release
>
>
> Documentation on the website is generated from the trunk and not from
> the
> latest stable release.
>
> Thus, newly implemented features appear in the documentation but they
> can't
> be used with the latest stable release. I lost time twice this week
> because
> of this.
>
> The routing by hostname do not work in 1.6.1 the way it is described

in

> the
> documentation and the "ignore" option of Zend_Translate described in
> the
> documentation won't be available before 1.7 release.
>
> Regards,
>
> Jean-Marc
> --
> View this message in context: http://www.nabble.com/Documentation-is-
> generated-from-the-trunk-not-from-the-latest-stable-release-
> tp19912997p19912997.html
> Sent from the Zend Doc mailing list archive at Nabble.com.

[wllm]

OK, the current policy is to only maintain docs on trunk to make it
easier for doc authors and translators to check in their changes (no
merge required). I'm not a big fan of this policy, to tell you the
truth. We'll probably be changing this soon. Right now I don't have the
change scheduled, and it will require some education so that everyone is
aware that they must merge changes to release branches, when it is
required, and how to do it.

,Wil

> -----Original Message-----
> From: Thomas Weidner [mailto:thomas.weidner@...]
> Sent: Friday, October 10, 2008 2:24 PM
> To: Wil Sinclair; fw-docs@...
> Subject: Re: Documentation is generated from the trunk not from the
> latest stable release
>
> Wil,
>
> what he've mentioned would still not be covered.
> The docu failures he mentioned for I18N were integrated for 1.6 but

the

> dev-team decided to delay them for 1.7.
> So this could still occur in such a case.
>
> The right solution is to have docu also branched.
> As new features are only for trunk this should be no problem.
> This way we could even provide a docu for the subreleases and a docu
> for the
> nightly snapshot the same time.
>
> Greetings
> Thomas Weidner, I18N Team Leader, Zend Framework
> http://www.thomasweidner.com
>
> ----- Original Message -----
> From: "Wil Sinclair" <wil@...>
> To: "Jean-Marc Fontaine" <jmf@...>; <fw-docs@...>
> Sent: Friday, October 10, 2008 9:54 PM
> Subject: RE: Documentation is generated from the trunk not from the
> latest
> stable release
>
>
> We've already discussed how to fix this on the site. What do you

people

> think would be best? Maybe just making the last production release
> available on the site with a clear statement saying what version they
> are associated with? If someone is working from trunk, it seems to me
> that they will likely also have the doc-fu to build the API docs.
>
> ,Wil
>
> > -----Original Message-----
> > From: Jean-Marc Fontaine [mailto:jmf@...]
> > Sent: Friday, October 10, 2008 12:01 AM
> > To: fw-docs@...
> > Subject: Documentation is generated from the trunk not from the
> latest
> > stable release
> >
> >
> > Documentation on the website is generated from the trunk and not

from
> > the
> > latest stable release.
> >
> > Thus, newly implemented features appear in the documentation but
they

> > can't
> > be used with the latest stable release. I lost time twice this week
> > because
> > of this.
> >
> > The routing by hostname do not work in 1.6.1 the way it is described
> in
> > the
> > documentation and the "ignore" option of Zend_Translate described in
> > the
> > documentation won't be available before 1.7 release.
> >
> > Regards,
> >
> > Jean-Marc
> > --
> > View this message in context:

http://www.nabble.com/Documentation-is-
> > generated-from-the-trunk-not-from-the-latest-stable-release-
> > tp19912997p19912997.html
> > Sent from the Zend Doc mailing list archive at Nabble.com.

[Jean-Marc Fontaine]

Thomas exactly described what I think would be best. :)

Jean-Marc