New branch: 5.4-js-rewrite

[Howard Lewis Ship <hl...@gmail.com>]

I've created a new branch for the changes I'm about to start in on, for 5.4.

These are going to be pretty sweeping changes, and I expect a lot of (test)
instability for the duration.

I'm concerned about merging these changes back into master at the end of
the process.  I don't want to freeze other work on the code base, but if
you think you're going to be doing more than minor surgery, it might be
nice to coordinate first on the dev mailing list.

I'm also concerned about the state of our documentation; these changes are
going to mean far, far more of our {since} caveats; I'm concerned that our
documentation will become a maze of these things! Having the ability to
create a parallel branch of the documentation (documentation as source
code, not as wiki pages) would be very nice.

Rolling up my sleeves ... ready to do some magic!



-- 
Howard M. Lewis Ship

Creator of Apache Tapestry

The source for Tapestry training, mentoring and support. Contact me to
learn how I can get you up and productive in Tapestry fast!

(971) 678-5210
http://howardlewisship.com

Re: New branch: 5.4-js-rewrite

[Ulrich Stärk <ul...@spielviel.de>]

On 23.06.2012 01:14, Howard Lewis Ship wrote:

> I'm also concerned about the state of our documentation; these changes are
> going to mean far, far more of our {since} caveats; I'm concerned that our
> documentation will become a maze of these things! Having the ability to
> create a parallel branch of the documentation (documentation as source
> code, not as wiki pages) would be very nice.

We had this discussion roughly two years ago and we put a great effort into moving away from
documentation in source code to documentation in a wiki. There were several reasons for that, most
notably decoupling documentation releases from code releases and giving non-committers the
opportunity to contribute.

I guess we could move the documentation to yet another format, back into vc and start releasing it
alongside Tapestry, thus making changes more clear. With a bit of integration work that might even
work with Apache's CMS thus allowing for anonymous contributions. I won't have the cycles to drive
this though until at least mid-august.

Uli

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

Re: New branch: 5.4-js-rewrite

[Howard Lewis Ship <hl...@gmail.com>]

On Wed, Jun 27, 2012 at 5:57 PM, Bob Harner <bo...@gmail.com> wrote:

> I'm a really big fan of having one set of docs with "since" and
> "deprecated" notations, the way we do it now. If I see something in the
> docs that needs improving, I'm only going to bother if there is just one
> version to edit.
>

I think what might be ideal is one set of documentation, but a control/tab
for each release, and the page would display just what was appropriate to
that page.  Anyone carrying around that code in their back pocket?



> On Jun 27, 2012 6:37 PM, "Howard Lewis Ship" <hl...@gmail.com> wrote:
>
> > On Wed, Jun 27, 2012 at 10:29 AM, Kalle Korhonen <
> > kalle.o.korhonen@gmail.com
> > > wrote:
> >
> > > On Wed, Jun 27, 2012 at 9:02 AM, Massimo Lusetti <ml...@gmail.com>
> > > wrote:
> > > > On Sat, Jun 23, 2012 at 1:14 AM, Howard Lewis Ship <hlship@gmail.com
> >
> > > wrote:
> > > >> I'm also concerned about the state of our documentation; these
> changes
> > > are
> > > >> going to mean far, far more of our {since} caveats; I'm concerned
> that
> > > our
> > > >> documentation will become a maze of these things! Having the ability
> > to
> > > >> create a parallel branch of the documentation (documentation as
> source
> > > >> code, not as wiki pages) would be very nice.
> > > > About docs... should we continue to think in terms of Confluence or
> > not?
> > >
> > > Well, we know Confluence, at least with Apache is a dead end. All
> > > projects are supposed to move off of Confluence generated sites by the
> > > end of the year (AFAIK, Confluence itself can still be used, they just
> > > don't want to support resource intensive static page generation from
> > > Confluence pages anymore). I agree with Uli though that Confluence has
> > > served us well - just because the documentation is never up-to-date at
> > > release time. I get what Howard is saying, but I'd take a an
> > > up-to-date documentation with caveats any day over multiple version
> > > specific documentation packages each of them possibly out of date.
> > >
> >
> > Yes, what I'd like would be a structure that lets us publish (even
> > retroactively) a 5.2 version of the docs, a 5.3 version, 5.4 version,
> etc.
> >
> > As new features are added, they can be added to the documentation
> (perhaps
> > with a temporary marker, like @since in Javadoc).
> >
> > When a deprecated feature is removed from the code, it could also be
> > removed from the documentation; perhaps will a cross-link to a release
> > where the feature existed.
> >
> > Periodically, we can remove the @since-like annotations; they just become
> > clutter after a couple of releases.
> >
> > However ... I'm super happy with how the documentation came together once
> > we were on Confluence!  The contributions by so many people made a huge
> > difference.
> >
> > It seems like the tools we want to use may nudge us towards having the
> > documentation outside the main Git repository,  possibly off Apache
> > entirely, so that the community can continue to collaborate on the
> > documentation without impediment.
> >
> >
> >
> >
> > >
> > > Kalle
> > >
> > > ---------------------------------------------------------------------
> > > To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
> > > For additional commands, e-mail: dev-help@tapestry.apache.org
> > >
> > >
> >
> >
> > --
> > Howard M. Lewis Ship
> >
> > Creator of Apache Tapestry
> >
> > The source for Tapestry training, mentoring and support. Contact me to
> > learn how I can get you up and productive in Tapestry fast!
> >
> > (971) 678-5210
> > http://howardlewisship.com
> >
>



-- 
Howard M. Lewis Ship

Creator of Apache Tapestry

The source for Tapestry training, mentoring and support. Contact me to
learn how I can get you up and productive in Tapestry fast!

(971) 678-5210
http://howardlewisship.com

Re: New branch: 5.4-js-rewrite

[Bob Harner <bo...@gmail.com>]

I'm a really big fan of having one set of docs with "since" and
"deprecated" notations, the way we do it now. If I see something in the
docs that needs improving, I'm only going to bother if there is just one
version to edit.
On Jun 27, 2012 6:37 PM, "Howard Lewis Ship" <hl...@gmail.com> wrote:

> On Wed, Jun 27, 2012 at 10:29 AM, Kalle Korhonen <
> kalle.o.korhonen@gmail.com
> > wrote:
>
> > On Wed, Jun 27, 2012 at 9:02 AM, Massimo Lusetti <ml...@gmail.com>
> > wrote:
> > > On Sat, Jun 23, 2012 at 1:14 AM, Howard Lewis Ship <hl...@gmail.com>
> > wrote:
> > >> I'm also concerned about the state of our documentation; these changes
> > are
> > >> going to mean far, far more of our {since} caveats; I'm concerned that
> > our
> > >> documentation will become a maze of these things! Having the ability
> to
> > >> create a parallel branch of the documentation (documentation as source
> > >> code, not as wiki pages) would be very nice.
> > > About docs... should we continue to think in terms of Confluence or
> not?
> >
> > Well, we know Confluence, at least with Apache is a dead end. All
> > projects are supposed to move off of Confluence generated sites by the
> > end of the year (AFAIK, Confluence itself can still be used, they just
> > don't want to support resource intensive static page generation from
> > Confluence pages anymore). I agree with Uli though that Confluence has
> > served us well - just because the documentation is never up-to-date at
> > release time. I get what Howard is saying, but I'd take a an
> > up-to-date documentation with caveats any day over multiple version
> > specific documentation packages each of them possibly out of date.
> >
>
> Yes, what I'd like would be a structure that lets us publish (even
> retroactively) a 5.2 version of the docs, a 5.3 version, 5.4 version, etc.
>
> As new features are added, they can be added to the documentation (perhaps
> with a temporary marker, like @since in Javadoc).
>
> When a deprecated feature is removed from the code, it could also be
> removed from the documentation; perhaps will a cross-link to a release
> where the feature existed.
>
> Periodically, we can remove the @since-like annotations; they just become
> clutter after a couple of releases.
>
> However ... I'm super happy with how the documentation came together once
> we were on Confluence!  The contributions by so many people made a huge
> difference.
>
> It seems like the tools we want to use may nudge us towards having the
> documentation outside the main Git repository,  possibly off Apache
> entirely, so that the community can continue to collaborate on the
> documentation without impediment.
>
>
>
>
> >
> > Kalle
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
> > For additional commands, e-mail: dev-help@tapestry.apache.org
> >
> >
>
>
> --
> Howard M. Lewis Ship
>
> Creator of Apache Tapestry
>
> The source for Tapestry training, mentoring and support. Contact me to
> learn how I can get you up and productive in Tapestry fast!
>
> (971) 678-5210
> http://howardlewisship.com
>

Re: New branch: 5.4-js-rewrite

[Howard Lewis Ship <hl...@gmail.com>]

On Wed, Jun 27, 2012 at 10:29 AM, Kalle Korhonen <kalle.o.korhonen@gmail.com
> wrote:

> On Wed, Jun 27, 2012 at 9:02 AM, Massimo Lusetti <ml...@gmail.com>
> wrote:
> > On Sat, Jun 23, 2012 at 1:14 AM, Howard Lewis Ship <hl...@gmail.com>
> wrote:
> >> I'm also concerned about the state of our documentation; these changes
> are
> >> going to mean far, far more of our {since} caveats; I'm concerned that
> our
> >> documentation will become a maze of these things! Having the ability to
> >> create a parallel branch of the documentation (documentation as source
> >> code, not as wiki pages) would be very nice.
> > About docs... should we continue to think in terms of Confluence or not?
>
> Well, we know Confluence, at least with Apache is a dead end. All
> projects are supposed to move off of Confluence generated sites by the
> end of the year (AFAIK, Confluence itself can still be used, they just
> don't want to support resource intensive static page generation from
> Confluence pages anymore). I agree with Uli though that Confluence has
> served us well - just because the documentation is never up-to-date at
> release time. I get what Howard is saying, but I'd take a an
> up-to-date documentation with caveats any day over multiple version
> specific documentation packages each of them possibly out of date.
>

Yes, what I'd like would be a structure that lets us publish (even
retroactively) a 5.2 version of the docs, a 5.3 version, 5.4 version, etc.

As new features are added, they can be added to the documentation (perhaps
with a temporary marker, like @since in Javadoc).

When a deprecated feature is removed from the code, it could also be
removed from the documentation; perhaps will a cross-link to a release
where the feature existed.

Periodically, we can remove the @since-like annotations; they just become
clutter after a couple of releases.

However ... I'm super happy with how the documentation came together once
we were on Confluence!  The contributions by so many people made a huge
difference.

It seems like the tools we want to use may nudge us towards having the
documentation outside the main Git repository,  possibly off Apache
entirely, so that the community can continue to collaborate on the
documentation without impediment.




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


-- 
Howard M. Lewis Ship

Creator of Apache Tapestry

The source for Tapestry training, mentoring and support. Contact me to
learn how I can get you up and productive in Tapestry fast!

(971) 678-5210
http://howardlewisship.com

Re: New branch: 5.4-js-rewrite

[Kalle Korhonen <ka...@gmail.com>]

On Wed, Jun 27, 2012 at 9:02 AM, Massimo Lusetti <ml...@gmail.com> wrote:
> On Sat, Jun 23, 2012 at 1:14 AM, Howard Lewis Ship <hl...@gmail.com> wrote:
>> I'm also concerned about the state of our documentation; these changes are
>> going to mean far, far more of our {since} caveats; I'm concerned that our
>> documentation will become a maze of these things! Having the ability to
>> create a parallel branch of the documentation (documentation as source
>> code, not as wiki pages) would be very nice.
> About docs... should we continue to think in terms of Confluence or not?

Well, we know Confluence, at least with Apache is a dead end. All
projects are supposed to move off of Confluence generated sites by the
end of the year (AFAIK, Confluence itself can still be used, they just
don't want to support resource intensive static page generation from
Confluence pages anymore). I agree with Uli though that Confluence has
served us well - just because the documentation is never up-to-date at
release time. I get what Howard is saying, but I'd take a an
up-to-date documentation with caveats any day over multiple version
specific documentation packages each of them possibly out of date.

Kalle

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

Re: New branch: 5.4-js-rewrite

[Massimo Lusetti <ml...@gmail.com>]

On Sat, Jun 23, 2012 at 1:14 AM, Howard Lewis Ship <hl...@gmail.com> wrote:

> I've created a new branch for the changes I'm about to start in on, for 5.4.
>
> These are going to be pretty sweeping changes, and I expect a lot of (test)
> instability for the duration.
>
> I'm concerned about merging these changes back into master at the end of
> the process.  I don't want to freeze other work on the code base, but if
> you think you're going to be doing more than minor surgery, it might be
> nice to coordinate first on the dev mailing list.

I'm sorry I'm a bit late here but have you (or should we) considered
using something like git-flow for development now that we are on pure
git?
BTW I think using the dev list as a coordination mechanism is plain right.

> I'm also concerned about the state of our documentation; these changes are
> going to mean far, far more of our {since} caveats; I'm concerned that our
> documentation will become a maze of these things! Having the ability to
> create a parallel branch of the documentation (documentation as source
> code, not as wiki pages) would be very nice.

About docs... should we continue to think in terms of Confluence or not?


Cheers
-- 
Massimo
http://meridio.blogspot.com

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