do we really need documentation and other docs in webapp context?

[Allen Gilliland <al...@sun.com>]

Just poking around a bit more and I noticed that there are some various 
bits of documentation stuff that are thrown into the application context 
during build time.  Thinks like ...

docs/*
CHANGES.txt
LICENSE.txt
NOTICE.txt
README.txt

I definitely believe these things should be part of the bundle that 
people download when they get a release, but I don't think they should 
actually be inside the webapp itself and therefore made available for 
people to browse to when the app is deployed.  Many (maybe most/all?) 
sites do not care to have that stuff inside that actually deployed webapp.

I'd like to remove them from being included in the assembled webapp. 
Anyone object?  They will still be part of the actual release, just not 
inside the webapp itself.

-- Allen

Re: do we really need documentation and other docs in webapp context?

[Allen Gilliland <al...@sun.com>]

Lance Lavandowska wrote:
> On 6/8/06, Allen Gilliland <al...@sun.com> wrote:
>>
>> > I'm curious, what open source webapps have you looked at that use
>> > this standard directory structure?
>>
>> hmmm, well there's these ...
>>
>> apache-ant-1.6.3/
>> commons-httpclient-2.0.2/
>> commons-lang-2.1/
>> hibernate-3.0/
>> jakarta-jmeter-2.0.3/
>> jakarta-log4j-1.2.8/
>> jakarta-struts-1.1/
>> jakarta-taglibs-standard-1.1.2/
>> javamail-1.3.1/
>> mysql-connector-java-3.0.14-production/
> 
> None of those are webapps.

not sure that really matters, we are still offering basically the same 
thing as most of those packages.

i any case, cocoon and jetspeed package the same ways as the ones above. 
  in fact, jetspeed is a pretty good example of what I think we should 
do with the roller package ...

Archive:  jetspeed-current.zip
    creating: jetspeed-1.5/
   inflating: jetspeed-1.5/FIXES.html
   inflating: jetspeed-1.5/INSTALL
   inflating: jetspeed-1.5/jetspeed.war
   inflating: jetspeed-1.5/LICENSE
   inflating: jetspeed-1.5/NOTES
   inflating: jetspeed-1.5/project.xml
   inflating: jetspeed-1.5/README
   inflating: jetspeed-1.5/WARNING

if you look inside the jetspeed war file you'll notice that none of the 
ALLCAPS files are duplicated their either.

-- Allen


> 
>> This can be debated all day, so maybe someone from ASF can offer any
>> suggestions based on how other ASF projects usually do it?
> 
> Cocoon and Jetspeed are the only other webapp I can think of from
> Apache (not saying there aren't others).
> 
> Lance

Re: do we really need documentation and other docs in webapp context?

[Lance Lavandowska <la...@gmail.com>]

On 6/8/06, Allen Gilliland <al...@sun.com> wrote:
>
> > I'm curious, what open source webapps have you looked at that use
> > this standard directory structure?
>
> hmmm, well there's these ...
>
> apache-ant-1.6.3/
> commons-httpclient-2.0.2/
> commons-lang-2.1/
> hibernate-3.0/
> jakarta-jmeter-2.0.3/
> jakarta-log4j-1.2.8/
> jakarta-struts-1.1/
> jakarta-taglibs-standard-1.1.2/
> javamail-1.3.1/
> mysql-connector-java-3.0.14-production/

None of those are webapps.

> This can be debated all day, so maybe someone from ASF can offer any
> suggestions based on how other ASF projects usually do it?

Cocoon and Jetspeed are the only other webapp I can think of from
Apache (not saying there aren't others).

Lance

Re: do we really need documentation and other docs in webapp context?

[Allen Gilliland <al...@sun.com>]

Dave Johnson wrote:
> On 6/8/06, Allen Gilliland <al...@sun.com> wrote:
>> Dave Johnson wrote:
>> > Right now we just ship two things 1) the self contained webapp and
>> > 2) the source release. To run Roller all you need is #1. I don't see a
>> > compelling reason to change that yet. Plus, I believe that docs and
>> > license/notices should be embedded in the app.
>>
>> I see.  Well, my opinion is that's kinda "eh".  I prefer a more standard
>> bundle for a number of reasons ...
> 
> I'm curious, what open source webapps have you looked at that use
> this standard directory structure?

hmmm, well there's these ...

apache-ant-1.6.3/
commons-httpclient-2.0.2/
commons-lang-2.1/
hibernate-3.0/
jakarta-jmeter-2.0.3/
jakarta-log4j-1.2.8/
jakarta-struts-1.1/
jakarta-taglibs-standard-1.1.2/
javamail-1.3.1/
mysql-connector-java-3.0.14-production/

... and that's just a quick selection from the packages i have currently 
exploded on my workstation.  all of them follow 2 simple conventions 
which i think we should use as well ...

1. the expoloded package contains the version number.

2. the package contains a simple directory structure which includes 
ALLCAPS files at the root, plus docs and other dirs with the rest of the 
files.


> 
> 
>> 1. It's 100% essential that we start marking releases with version
>> numbers.  When you tar/gzip the package it should come out in a
>> directory such as roller-x.y.z.
> 
> I don't think it's 100% essential.

I was being overly dramatic, but I still think there is almost no good 
reason not to do that.


> 
> 
>> 2. As we have been discussing there are certainly things that belong in
>> the downloadable package but not in the webapp itself.
> 
> I still think docs, and even the install doc, belongs in the webapp
> and should be browsable. I also believe license/notice file belongs
> embedded in the app itself.

This can be debated all day, so maybe someone from ASF can offer any 
suggestions based on how other ASF projects usually do it?


> 
> 
>> 3. Eventually we should package as a .war file and not just a directory
>> tree for the app, and in that case it makes more sense to have an actual
>> bundle with the .war included, rather than making the .war the only
>> distribution.
> 
> Yes, .war packaging is a good thing.
> 
> 
>> 4. Using a bundle gives us much more flexibility to include other things
>> that may be useful to the user, but which shouldn't really be directly
>> included in the core webapp.  themes?  plugins?  editors?
> 
> I'd prefer to make themes, plugins and editors available separately,
> but I do agree that there will be some other things that belong there.

I agree, they should be separate, i was mainly using it as an example. 
The point is that there are things that should be part of the 
downloadable Roller distribution that don't belong in the webapp.


> 
> 
>> I don't really think it's ideal to only package the webapp for the
>> release and then end up having to put things in the webapp which
>> shouldn't be there so that that they are in the download.  It's not that
>> hard to setup a very simple structure for the download bundle and make
>> it part of the build process.  I am more than willing to do this.
> 
> If you have time to do that and to update the install / dev guide 
> accordingly,
> then please write up a short proposal for the new release dir structure.

Affirmative.

-- Allen


> 
> - Dave

Re: do we really need documentation and other docs in webapp context?

[Dave Johnson <sn...@gmail.com>]

On 6/8/06, Allen Gilliland <al...@sun.com> wrote:
> Dave Johnson wrote:
> > Right now we just ship two things 1) the self contained webapp and
> > 2) the source release. To run Roller all you need is #1. I don't see a
> > compelling reason to change that yet. Plus, I believe that docs and
> > license/notices should be embedded in the app.
>
> I see.  Well, my opinion is that's kinda "eh".  I prefer a more standard
> bundle for a number of reasons ...

I'm curious, what open source webapps have you looked at that use
this standard directory structure?


> 1. It's 100% essential that we start marking releases with version
> numbers.  When you tar/gzip the package it should come out in a
> directory such as roller-x.y.z.

I don't think it's 100% essential.


> 2. As we have been discussing there are certainly things that belong in
> the downloadable package but not in the webapp itself.

I still think docs, and even the install doc, belongs in the webapp
and should be browsable. I also believe license/notice file belongs
embedded in the app itself.


> 3. Eventually we should package as a .war file and not just a directory
> tree for the app, and in that case it makes more sense to have an actual
> bundle with the .war included, rather than making the .war the only
> distribution.

Yes, .war packaging is a good thing.


> 4. Using a bundle gives us much more flexibility to include other things
> that may be useful to the user, but which shouldn't really be directly
> included in the core webapp.  themes?  plugins?  editors?

I'd prefer to make themes, plugins and editors available separately,
but I do agree that there will be some other things that belong there.


> I don't really think it's ideal to only package the webapp for the
> release and then end up having to put things in the webapp which
> shouldn't be there so that that they are in the download.  It's not that
> hard to setup a very simple structure for the download bundle and make
> it part of the build process.  I am more than willing to do this.

If you have time to do that and to update the install / dev guide accordingly,
then please write up a short proposal for the new release dir structure.

- Dave

Re: do we really need documentation and other docs in webapp context?

[Anil Gangolli <an...@busybuddha.org>]

Some comments inline... FWIW...

----- Original Message ----- 
>
> 1. It's 100% essential that we start marking releases with version 
> numbers.  When you tar/gzip the package it should come out in a directory 
> such as roller-x.y.z.

I think this is good for the top-most level, but I expect that the top level 
directory of the webapp is a stable name within that.

>
> 2. As we have been discussing there are certainly things that belong in 
> the downloadable package but not in the webapp itself.

Agree.

> 3. Eventually we should package as a .war file and not just a directory 
> tree for the app, and in that case it makes more sense to have an actual 
> bundle with the .war included, rather than making the .war the only 
> distribution.

I no longer rate this of high importance.

I think people typically still go editing files under WEB-INF prior to 
installation, whether it is to extract a copy of or change roller.properties 
or to add some JBoss or app-server-specific auxiliary web.xml stuff.  For 
the people that will just drop it into Tomcat and go, the .war is nice. 
Otherwise, it just adds an extra unzip step before editing and repacking.

Also, with the current required-jars overlay, some repacking is also 
required.


> 4. Using a bundle gives us much more flexibility to include other things 
> that may be useful to the user, but which shouldn't really be directly 
> included in the core webapp.  themes?  plugins?  editors?

Agree here; we should have things outside the web app in the bundle.

> I don't really think it's ideal to only package the webapp for the release 
> and then end up having to put things in the webapp which shouldn't be 
> there so that that they are in the download.  It's not that hard to setup 
> a very simple structure for the download bundle and make it part of the 
> build process.  I am more than willing to do this.

Overall, I agree.

> -- Allen
>
>
>>
>> - Dave
>

--Anil

Re: do we really need documentation and other docs in webapp context?

[Allen Gilliland <al...@sun.com>]

Dave Johnson wrote:
> On 6/8/06, Allen Gilliland <al...@sun.com> wrote:
>> Dave Johnson wrote:
>> >> docs/*
>> >
>> > I strongly object to removing the docs from the webapp. The docs for
>> > the current version of the app should be made available within the
>> > app. The should be moved to roller-ui so they are not polluting the
>> > URL space.
>>
>> I am fine with that.  In general I think the issue with docs is a coin
>> flip for me.  On one hand I definitely see the benefits of including the
>> docs in a browsable location of the app with each release.  However, on
>> the flip side there is something to be said for not polluting the webapp
>> with things that people don't really need, we can package the docs in
>> the bundle and not in the webapp and if people want to move them into
>> the app then they can do so.  there is also something to be said for
>> maintaining online documentation in a central location like
>> roller.apache.org/docs and not duplicating those docs over and over 
>> again.
> 
> It's a lot easier for the user to simply click on the docs link and see the
> user guide than it is for them to go to our website and search around for
> the docs that correspond to the version of Roller that they are using.

I think we may be talking about 2 slightly different types of 
documentation.  I see 2 types ...

1. Admin documentation.  Stuff about how to setup/upgrade Roller, info 
about change logs and versions, etc.  Basically, all the documentation a 
Roller blogger doesn't necessarily care about.

2. User documentation.  Stuff about how to use Roller, macro guides, 
tips on template customizations, plugins/editors help, etc.  Stuff that 
any user may want access to.

In my opinion it doesn't make any sense for #1 to be inside the 
application.  Those docs are really only meant for the person installing 
/maintaining the site and are meant to be read before the app is installed.

I think it's fine if the User docs are inside the app.  I don't think it 
has to be, but I can see this being convenient.


> 
> 
>> i consider the "release" and the
>> "webapp" to be 2 different things.  the webapp is just what gets run in
>> the container, i.e. what you get in build/roller.  the release is the
>> webapp plus whatever else we think is useful, typically like legal
>> notices, docs, examples, plugins/addons, etc.
> 
> Right now we just ship two things 1) the self contained webapp and
> 2) the source release. To run Roller all you need is #1. I don't see a
> compelling reason to change that yet. Plus, I believe that docs and
> license/notices should be embedded in the app.

I see.  Well, my opinion is that's kinda "eh".  I prefer a more standard 
bundle for a number of reasons ...

1. It's 100% essential that we start marking releases with version 
numbers.  When you tar/gzip the package it should come out in a 
directory such as roller-x.y.z.

2. As we have been discussing there are certainly things that belong in 
the downloadable package but not in the webapp itself.

3. Eventually we should package as a .war file and not just a directory 
tree for the app, and in that case it makes more sense to have an actual 
bundle with the .war included, rather than making the .war the only 
distribution.

4. Using a bundle gives us much more flexibility to include other things 
that may be useful to the user, but which shouldn't really be directly 
included in the core webapp.  themes?  plugins?  editors?

I don't really think it's ideal to only package the webapp for the 
release and then end up having to put things in the webapp which 
shouldn't be there so that that they are in the download.  It's not that 
hard to setup a very simple structure for the download bundle and make 
it part of the build process.  I am more than willing to do this.

-- Allen


> 
> - Dave

Re: do we really need documentation and other docs in webapp context?

[Dave Johnson <sn...@gmail.com>]

On 6/8/06, Allen Gilliland <al...@sun.com> wrote:
> Dave Johnson wrote:
> >> docs/*
> >
> > I strongly object to removing the docs from the webapp. The docs for
> > the current version of the app should be made available within the
> > app. The should be moved to roller-ui so they are not polluting the
> > URL space.
>
> I am fine with that.  In general I think the issue with docs is a coin
> flip for me.  On one hand I definitely see the benefits of including the
> docs in a browsable location of the app with each release.  However, on
> the flip side there is something to be said for not polluting the webapp
> with things that people don't really need, we can package the docs in
> the bundle and not in the webapp and if people want to move them into
> the app then they can do so.  there is also something to be said for
> maintaining online documentation in a central location like
> roller.apache.org/docs and not duplicating those docs over and over again.

It's a lot easier for the user to simply click on the docs link and see the
user guide than it is for them to go to our website and search around for
the docs that correspond to the version of Roller that they are using.


> i consider the "release" and the
> "webapp" to be 2 different things.  the webapp is just what gets run in
> the container, i.e. what you get in build/roller.  the release is the
> webapp plus whatever else we think is useful, typically like legal
> notices, docs, examples, plugins/addons, etc.

Right now we just ship two things 1) the self contained webapp and
2) the source release. To run Roller all you need is #1. I don't see a
compelling reason to change that yet. Plus, I believe that docs and
license/notices should be embedded in the app.

- Dave

Re: do we really need documentation and other docs in webapp context?

[Allen Gilliland <al...@sun.com>]

Dave Johnson wrote:
> On 6/8/06, Allen Gilliland <al...@sun.com> wrote:
>> Just poking around a bit more and I noticed that there are some various
>> bits of documentation stuff that are thrown into the application context
>> during build time.  Thinks like ...
>>
>> docs/*
> 
> I strongly object to removing the docs from the webapp. The docs for
> the current version of the app should be made available within the
> app. The should be moved to roller-ui so they are not polluting the
> URL space.

I am fine with that.  In general I think the issue with docs is a coin 
flip for me.  On one hand I definitely see the benefits of including the 
docs in a browsable location of the app with each release.  However, on 
the flip side there is something to be said for not polluting the webapp 
with things that people don't really need, we can package the docs in 
the bundle and not in the webapp and if people want to move them into 
the app then they can do so.  there is also something to be said for 
maintaining online documentation in a central location like 
roller.apache.org/docs and not duplicating those docs over and over again.


> 
>> CHANGES.txt
>> LICENSE.txt
>> NOTICE.txt
>> README.txt
>> I definitely believe these things should be part of the bundle that
>> people download when they get a release, but I don't think they should
>> actually be inside the webapp itself and therefore made available for
> 
> Right now the release is self-contained in a directory called "roller" and
> I'd really like to keep it that way if at all possible.

i don't understand this comment.  i consider the "release" and the 
"webapp" to be 2 different things.  the webapp is just what gets run in 
the container, i.e. what you get in build/roller.  the release is the 
webapp plus whatever else we think is useful, typically like legal 
notices, docs, examples, plugins/addons, etc.

unless i am thinking of the wrong directory then i believe you are just 
talking about the "roller" webapp directory right?

i don't think we should plan to keep everything in there.  i think that 
directory is where we build the webapp from, but there should be another 
directory that represents a release package, which would include the webapp.


> 
> 
>> people to browse to when the app is deployed.  Many (maybe most/all?)
>> sites do not care to have that stuff inside that actually deployed 
>> webapp.
> 
> I object here too. These should be part of the app, but they don't
> need to be browsable, so they could be moved into WEB-INF.

really?  I feel like that is against standard operating procedures.  My 
take on most app downloads is that you would get something like this ...

roller-x.y.z/
roller-x.y.z/CHANGES.txt
roller-x.y.z/LICENSE.txt
roller-x.y.z/NOTICE.txt
roller-x.y.z/README.txt
roller-x.y.z/bin/*
roller-x.y.z/docs/*
roller-x.y.z/plugins/*
roller-x.y.z/examples/*
roller-x.y.z/extras/*
roller-x.y.z/lib/*
roller-x.y.z/src/*
roller-x.y.z/roller.war (or we can do dist/roller?)

we don't necessarily have/need all those dirs, but you get the idea.

I don't see why all the legal/copyright/etc stuff needs to be inside the 
deployed application?  Nobody is going to look at it there.  Plus it 
would be duplicated assuming we include it at the root of the package as 
well.

I think the same basically applies for the docs.  Supposedly we want 
people to look at the docs *before* deploying the application, and 
that's why it makes sense that they exist outside the app.

-- Allen


> 
> - Dave

Re: do we really need documentation and other docs in webapp context?

[Dave Johnson <sn...@gmail.com>]

On 6/8/06, Allen Gilliland <al...@sun.com> wrote:
> Just poking around a bit more and I noticed that there are some various
> bits of documentation stuff that are thrown into the application context
> during build time.  Thinks like ...
>
> docs/*

I strongly object to removing the docs from the webapp. The docs for
the current version of the app should be made available within the
app. The should be moved to roller-ui so they are not polluting the
URL space.

> CHANGES.txt
> LICENSE.txt
> NOTICE.txt
> README.txt
> I definitely believe these things should be part of the bundle that
> people download when they get a release, but I don't think they should
> actually be inside the webapp itself and therefore made available for

Right now the release is self-contained in a directory called "roller" and
I'd really like to keep it that way if at all possible.


> people to browse to when the app is deployed.  Many (maybe most/all?)
> sites do not care to have that stuff inside that actually deployed webapp.

I object here too. These should be part of the app, but they don't
need to be browsable, so they could be moved into WEB-INF.

- Dave