You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@jackrabbit.apache.org by "Roy T. Fielding" <fi...@gbiv.com> on 2006/03/15 22:00:04 UTC
move site outside of maven?
I am increasingly finding that 95% or more of the maven generated
information is too detailed and changes too often to be useful for
a real site. In particular, the generators randomly change anchor
names for no good reason, which makes oversight of documentation
impossible. I also find the content of the maven generated info,
such as the list of project devs, to be mostly useless and not
very configurable.
I am thinking of switching to plain Anakia for the site and using
hand-crafted XML pages for project information. We can then manually
publish the javadocs on a per-major-version basis.
Are there any objections to that?
We need to update the README files. In particular, we should be
giving credit to everyone whose work has made it into the product,
whereas right now we only list the credits for the initial commit.
Perhaps we should move that stuff to a CHANGES.txt file?
....Roy
Re: move site outside of maven?
Posted by Jukka Zitting <ju...@gmail.com>.
Hi,
On 3/20/06, Fabrizio Giustina <fg...@apache.org> wrote:
> All those reports are simply not meant to be checked into a scm
> repository... I know that the Apache guidelines tells to "not to
> modify files directly in the site directory, but check them into
> subversion instead" but I don't think that such recommendation could
> apply to files that are totally generated from other sources.
I pretty much agree with you, but I do see a point in the guidelines
as well. The more complex the site publishing process is, the easier
it is for it to get broken due to either a bug or a user error. For
example it would be easy for me to forget the LANG=en setting from a
maven site:sshdeploy command, which would result in all the reports
being localized to Finnish until someone notices to fix the problem.
:-) I could also have some transient files laying around that might
accidentally get published on the web site even though no record of
them is ever stored in version control.
One way to make "direct" publishing approach the reliability of going
through subversion would be to have the site generation performed on a
server with no manual intervention. For example a nightly script could
automatically checkout the latest source tree, generate the site, and
deploy it. I've even seen setups where a subversion post-commit script
generates and deploys the site.
I don't suppose the ASF infrastructure will support such a feature
(with Maven/Forrest/Anakia/etc.) in near future, so the best way to do
something like that would probably be to apply for a
jackrabbit.zones.apache.org and set up a site build script there.
If bypassing subversion is OK for site publishing, then we could
simply copy the generated site files to the public site location.
Otherwise we could have the site build script prepare a subversion
changeset that could simply be committed once the staging site has
been reviewed. This could possibly be a "best of both worlds" option.
PS. An old thread about the same issue:
http://thread.gmane.org/gmane.comp.apache.jackrabbit.devel/354
BR,
Jukka Zitting
--
Yukatan - http://yukatan.fi/ - info@yukatan.fi
Software craftsmanship, JCR consulting, and Java development
Re: move site outside of maven?
Posted by Jukka Zitting <ju...@gmail.com>.
Hi,
On 3/21/06, Roy T. Fielding <fi...@gbiv.com> wrote:
> I think just one copy per MAJOR release is enough, with that copy
> being updated only when a new release is made. We are talking about
> 1600 or so files per xref copy. Of course, we could always make an
> exception if it turns out the online xref is heavily used and one
> of the minor releases does a reorg.
Sounds good.
BR,
Jukka Zitting
--
Yukatan - http://yukatan.fi/ - info@yukatan.fi
Software craftsmanship, JCR consulting, and Java development
Re: move site outside of maven?
Posted by "Roy T. Fielding" <fi...@gbiv.com>.
On Mar 20, 2006, at 3:11 PM, Jukka Zitting wrote:
> I think it would make sense to have a stripped down (no xrefs or other
> troublesome reports) Maven site as the frequently updated main site,
> but include static versions of full docs (Maven sites with full
> reports generated using the maven.xdoc.version settings) for each
> MAJOR and MINOR release (no need to do that for PATCH releases).
I think just one copy per MAJOR release is enough, with that copy
being updated only when a new release is made. We are talking about
1600 or so files per xref copy. Of course, we could always make an
exception if it turns out the online xref is heavily used and one
of the minor releases does a reorg.
....Roy
Re: move site outside of maven?
Posted by Jukka Zitting <ju...@gmail.com>.
Hi,
On 3/20/06, Mark Slater <li...@humanesoftware.com> wrote:
> From the perspective of one such (more) occasional user, I would not
> want the main site to change between releases. Once jackrabbit 1.0 or
> 1.1 is released, I'm not likely to continue building from source. So
> when I go to the jackrabbit.apache.org website, I expect to find the
> docs (xref, javadocs, user documentation, etc.) for the current
> release.
I'd rather not freeze the site between releases, but it would
certainly make sense to have frozen doc snapshots of the released
versions.
I think it would make sense to have a stripped down (no xrefs or other
troublesome reports) Maven site as the frequently updated main site,
but include static versions of full docs (Maven sites with full
reports generated using the maven.xdoc.version settings) for each
MAJOR and MINOR release (no need to do that for PATCH releases).
BR,
Jukka Zitting
--
Yukatan - http://yukatan.fi/ - info@yukatan.fi
Software craftsmanship, JCR consulting, and Java development
Re: move site outside of maven?
Posted by Mark Slater <li...@humanesoftware.com>.
On Mar 20, 2006, at 1:04 PM, Jukka Zitting wrote:
>
>> My guess is that the best way to handle this is to use Maven's
>> version of anakia to generate the site (for developers) but only
>> deploy a small subset of that to jackrabbit.apache.org (without
>> the reports, xref, etc.).
>
> OK, I think that's reasonable. How about if we also generated static
> javadoc and xref reports for each release? That should be good enough
> for the occasional user.
>
From the perspective of one such (more) occasional user, I would not
want the main site to change between releases. Once jackrabbit 1.0 or
1.1 is released, I'm not likely to continue building from source. So
when I go to the jackrabbit.apache.org website, I expect to find the
docs (xref, javadocs, user documentation, etc.) for the current
release. If I'm downloading the binaries for jackrabbit, I should not
have to also download the source code for that version and run maven
to generate all the reports myself - that should be available to me
(assuming I'm using the current release) on the jackrabbit web site.
There are people who don't use maven themselves, and requiring them
to build the site on their own with a tool they would have to
download and install could be an "undue burden".
If the site were only generated once for each release, and that
generated site checked into subversion, it seems like that would
solve most of the issues. You can use the maven.xdoc.date and
maven.xdoc.version properties to place the date generated and version
of the software in the grey bar along the top, making it clear to
visitors what version of the documentation they're looking at. I
don't know how often user documentation (the FAQ, Getting Started,
First Hops, etc) needs to be updated between releases, but if it is
rare, it shouldn't be hard to regenerate the site, and only check in
the changed user docs.
Mark
Re: move site outside of maven?
Posted by Jukka Zitting <ju...@gmail.com>.
Hi,
On 3/20/06, Roy T. Fielding <fi...@gbiv.com> wrote:
> One idea was to move these generated files to a staging area and
> reproduce from there, but that failed to generate enough volunteers
> on site-dev (mostly because people insist on defending forrest or
> maven or whatever as the uber-tool instead of just doing the work).
Ah, pity. It doesn't sound like it would be too complex to do
something like that. I couldn't find site-dev archives for more
details. Is the list private?
> My guess is that the best way to handle this is to use Maven's
> version of anakia to generate the site (for developers) but only
> deploy a small subset of that to jackrabbit.apache.org (without
> the reports, xref, etc.).
OK, I think that's reasonable. How about if we also generated static
javadoc and xref reports for each release? That should be good enough
for the occasional user.
We can also handle the alternating row issue with the following
maven.xml addition:
<postGoal name="xdoc">
<ant:replaceregexp
match="<tr class="b">"
replace="<tr class="a">" flags="g" byline="true">
<ant:fileset dir="${maven.docs.dest}" includes="**/*.html"/>
</ant:replaceregexp>
</postGoal>
It makes the tables slightly less readable, but cuts down the amount
extra changes. And as Roy mentioned, we could always compensate with
extra CSS.
BR,
Jukka Zitting
--
Yukatan - http://yukatan.fi/ - info@yukatan.fi
Software craftsmanship, JCR consulting, and Java development
Re: move site outside of maven?
Posted by Fabrizio Giustina <fg...@apache.org>.
On 3/20/06, Roy T. Fielding <fi...@gbiv.com> wrote:
> It isn't a recommendation. It is mandatory to have a simple mechanism
> that reproduces the exact content that was on the site, so that we can
> quickly check for content that has been modified by a crack on www.
> Maven site:deploy generates different content every time -- it does
> not qualify at all.
I don't agree that "Maven site:deploy generates different content
every time": if you start from the exact source code it will generate
an identical copy of the documentation, except for generation dates
and execution times for junit. And I don't think that replacing pages
on the live site with identical pages with this normal changes means
"not being able to reproduce the exact content that was on the site"
> One idea was to move these generated files to a staging area and
> reproduce from there, but that failed to generate enough volunteers
> on site-dev (mostly because people insist on defending forrest or
> maven or whatever as the uber-tool instead of just doing the work).
That is a good solution, and we are already do that with maven. You
can setup a staging site where everything gets published and only sync
the live website using rsync from there. Xdoc already supports this
kind of steps.
About defending tools: I absolutely don't want to pointlessly defend
maven, I am just expressing my personal though on some problems that
IMHO are not problems at all.
You first pointed out that you would like to drop maven because of
problems in the documentation it generates and I just wanted to
understand what kind of problems did you had... for most of these the
tool used is not important at all: if you want to have a test report
on the website you will have changing execution times regardless of
the tool you use to generate it, and if you don't want to have such
report you can simply turn it off without having to swith to a
different tool for such reason.
> In any case, it is incredibly brain dead to set up automated
> instructions in maven so that anyone with a login on apache.org
> can ssh the content to the live website. I don't think Maven
> would appreciate it if I checked out an old version of their sources
> and accidentally ran that command. Unlike most people, I do have the
> permissions necessary to wipe out everyone's website on apache.org.
I can't get the point here... you (or anybody else with the needed
right) could wipe out any website on apache.org, both if it was
published using maven or not. And all the content could be easily
republished both recreating it using maven or checking it out from
subversion...
> The reports that Maven produces are very useful for a developer to
> generate on their own machine. I don't think anyone else should be
> subjected to the reports generated on *my* machine, since OS X's
> version of java is not what server-side developers care about when
> they go looking for problems to fix.
The only report which is heavily system dependent is probably the
junit one. But anyway I find Xref source code, javadocs, changes
reports very useful and not enviroment dependent at all. And having a
test report generated from a different machine than mine turned out to
be useful in several situation, when something on my env was not setup
correctly.
> My guess is that the best way to handle this is to use Maven's
> version of anakia to generate the site (for developers) but only
> deploy a small subset of that to jackrabbit.apache.org (without
> the reports, xref, etc.).
That could probably be a solution, just checking in the main docs and
leaving reports in a "developer sections" where nothing cames form
subversion
fabrizio
Re: move site outside of maven?
Posted by "Roy T. Fielding" <fi...@gbiv.com>.
On Mar 20, 2006, at 8:07 AM, Fabrizio Giustina wrote:
> On 3/20/06, Jukka Zitting <ju...@gmail.com> wrote:
>> I'm seeing at least the following problems:
>> [...]
>> 2) The line numbers in the source cross reference reports cause
>> almost
>> the entire cross reference file to be modified whenever lines are
>> added or removed from the source files.
>
> well, that's perfectly normal, if you want to have xref updated with
> the latest version of the source code... I don't think this should be
> a problem
>
>> 3) The included execution times in the JUnit test report cause the
>> entire file to be modified whenever the site is generated.
>
> since execution time can't be perfectly stable across different runs
> that's another expected thing...
>
>> 4) My setup seems to generate the class="a" and class="b" attributes
>> of generated table rows in a different order than Roy's setup.
That is the random change I was talking about -- it will change the
order even if nothing in the content has changed.
> If I remember well, that's probably simply because the total row
> number during the site generation is a global variable, so it's enough
> to have a single added row in a table that other css classes could
> shift....
Then the generator should be fixed to not add class names based on
the number of entries. There are many other ways to code CSS.
> All those reports are simply not meant to be checked into a scm
> repository... I know that the Apache guidelines tells to "not to
> modify files directly in the site directory, but check them into
> subversion instead" but I don't think that such recommendation could
> apply to files that are totally generated from other sources.
It isn't a recommendation. It is mandatory to have a simple mechanism
that reproduces the exact content that was on the site, so that we can
quickly check for content that has been modified by a crack on www.
Maven site:deploy generates different content every time -- it does
not qualify at all.
One idea was to move these generated files to a staging area and
reproduce from there, but that failed to generate enough volunteers
on site-dev (mostly because people insist on defending forrest or
maven or whatever as the uber-tool instead of just doing the work).
In any case, it is incredibly brain dead to set up automated
instructions in maven so that anyone with a login on apache.org
can ssh the content to the live website. I don't think Maven
would appreciate it if I checked out an old version of their sources
and accidentally ran that command. Unlike most people, I do have the
permissions necessary to wipe out everyone's website on apache.org.
The reports that Maven produces are very useful for a developer to
generate on their own machine. I don't think anyone else should be
subjected to the reports generated on *my* machine, since OS X's
version of java is not what server-side developers care about when
they go looking for problems to fix.
My guess is that the best way to handle this is to use Maven's
version of anakia to generate the site (for developers) but only
deploy a small subset of that to jackrabbit.apache.org (without
the reports, xref, etc.).
....Roy
Re: move site outside of maven?
Posted by Fabrizio Giustina <fg...@apache.org>.
Hi,
On 3/20/06, Jukka Zitting <ju...@gmail.com> wrote:
> I'm seeing at least the following problems:
> [...]
> 2) The line numbers in the source cross reference reports cause almost
> the entire cross reference file to be modified whenever lines are
> added or removed from the source files.
well, that's perfectly normal, if you want to have xref updated with
the latest version of the source code... I don't think this should be
a problem
> 3) The included execution times in the JUnit test report cause the
> entire file to be modified whenever the site is generated.
since execution time can't be perfectly stable across different runs
that's another expected thing...
> 4) My setup seems to generate the class="a" and class="b" attributes
> of generated table rows in a different order than Roy's setup.
If I remember well, that's probably simply because the total row
number during the site generation is a global variable, so it's enough
to have a single added row in a table that other css classes could
shift....
All those reports are simply not meant to be checked into a scm
repository... I know that the Apache guidelines tells to "not to
modify files directly in the site directory, but check them into
subversion instead" but I don't think that such recommendation could
apply to files that are totally generated from other sources.
If you had any file or resources that show up on the website without
any processing that could be true, but when html pages are simply a
"translation" of xdoc documents having the source xdoc file checked
into subversion should be enough. And for all the reports that only
dependes from the source code like Xref I can't see any reason why
having the source code in svn is not enough (sounds just like checking
in .class files to me...).
My suggestion is to check if having xdocs into subversion is enough:
IMHO the project guidelines simply don't take into consideration the
use of Maven (or any similar tool) that doesn't generate only static
documentation, but very "dynamic" reports.
Using Maven you can also easily deploy (to the live site or to a stage
site) all the generated documentation and I'm sure you will find that
better that going through svn for any change.
fabrizio
Re: move site outside of maven?
Posted by Jukka Zitting <ju...@gmail.com>.
Hi,
On 3/15/06, Fabrizio Giustina <fg...@apache.org> wrote:
> On 3/15/06, Roy T. Fielding <fi...@gbiv.com> wrote:
> > In particular, the generators randomly change anchor
> > names for no good reason, which makes oversight of documentation
> > impossible.
>
> This should not happen, where are you seeing this behavior?
I just retried generating the Jackrabbit site using Roy's instructions
from http://article.gmane.org/gmane.comp.apache.jackrabbit.devel/4586
(only added LANG=en to the maven site:deploy line to get the various
reports in English :-).
I'm seeing at least the following problems:
1) For some reason the checked-out test-xref contain "\.\." sequences
instead of ".." for parent references in stylesheet paths. My build
fixes this problem so this is probably some
problem in Roy's environment.
2) The line numbers in the source cross reference reports cause almost
the entire cross reference file to be modified whenever lines are
added or removed from the source files.
3) The included execution times in the JUnit test report cause the
entire file to be modified whenever the site is generated.
4) My setup seems to generate the class="a" and class="b" attributes
of generated table rows in a different order than Roy's setup.
There are some other problems as well with the generated reports, but
these ones seem to generate the most of the extra changes that make
the site commits virtually unreadable.
BR,
Jukka Zitting
--
Yukatan - http://yukatan.fi/ - info@yukatan.fi
Software craftsmanship, JCR consulting, and Java development
Re: move site outside of maven?
Posted by Fabrizio Giustina <fg...@apache.org>.
Hi Roy
maybe I can help undestanding if there are real issues with Maven,
before thinking about swithing to Anakia... some of the things
mentioned here sound pretty new to me
On 3/15/06, Roy T. Fielding <fi...@gbiv.com> wrote:
> I am increasingly finding that 95% or more of the maven generated
> information is too detailed and changes too often to be useful for
> a real site. In particular, the generators randomly change anchor
> names for no good reason, which makes oversight of documentation
> impossible.
This should not happen, where are you seeing this behavior?
> I also find the content of the maven generated info,
> such as the list of project devs, to be mostly useless and not
> very configurable.
what would you actually like to configure for the dev list that you
couldn't do? It just lists devs and contributors from the project pom,
so apart from this list there is no additional customization needed.
Keep in mind that for each report that you don't like you can simply
exclude it or just replace it with a totally custom xdoc.
> I am thinking of switching to plain Anakia for the site and using
> hand-crafted XML pages for project information.
well, as just said you can already do that using maven, if needed.
I also don't think that all the maven reports are useless... I find
pretty useful to find test reports, xrefs, change logs published, and
there are plenty of other reports/plugins that jackrabbit doesn't use
at the moment that could be added in future and bring more value to
the documentation or help developers (e.g. coverage report, checkstyle
...).
my 2c
fabrizio
Re: move site outside of maven?
Posted by Jukka Zitting <ju...@gmail.com>.
Hi,
On 3/15/06, Fabrizio Giustina <fg...@apache.org> wrote:
> On 3/15/06, Jukka Zitting <ju...@gmail.com> wrote:
> > but as long as the generated HTML needs to go through SVN this seems a
> > bit troublesome. How does the Maven project manage their site?
>
> maven site
> maven site:sshdeploy
>
> not going through SVN at all... html pages are just generated stuff
> and can be created on the fly from xdoc, so there is no reason to keep
> them in svn
That's as I expected. I agree that it doesn't make much sense to have
the generated site in SVN as long as it can easily be regenerated from
the SVN sources.
The infrastructure instructions at
http://www.apache.org/dev/project-site.html however suggest that the
site should go through SVN, and I think I recall some arguments as to
why this should be the preferred (if not only!) way to publish a site.
Does anyone have more accurate info on the web site policy?
BR,
Jukka Zitting
--
Yukatan - http://yukatan.fi/ - info@yukatan.fi
Software craftsmanship, JCR consulting, and Java development
Re: move site outside of maven?
Posted by Fabrizio Giustina <fg...@apache.org>.
On 3/15/06, Jukka Zitting <ju...@gmail.com> wrote:
> but as long as the generated HTML needs to go through SVN this seems a
> bit troublesome. How does the Maven project manage their site?
maven site
maven site:sshdeploy
not going through SVN at all... html pages are just generated stuff
and can be created on the fly from xdoc, so there is no reason to keep
them in svn
fabrizio
Re: move site outside of maven?
Posted by Jukka Zitting <ju...@gmail.com>.
Hi,
On 3/15/06, Roy T. Fielding <fi...@gbiv.com> wrote:
> I am increasingly finding that 95% or more of the maven generated
> information is too detailed and changes too often to be useful for
> a real site. In particular, the generators randomly change anchor
> names for no good reason, which makes oversight of documentation
> impossible. I also find the content of the maven generated info,
> such as the list of project devs, to be mostly useless and not
> very configurable.
I've found many of the Maven reports quite useful (for example the
source xref is a great tool for quickly navigating the source tree),
but the current site deployment model doesn't really support that use
case. We should either have the whole site updated nightly or move the
reports somewhere else where they can be updated more frequently than
the main site.
The Maven site generation process also seems to generate slightly
different results in different environments. During the few times I've
tried to update the site based on Roy's instructions I've ended up
with a changeset that touches almost all files within the site. For
example during the 0.9 release I only committed the changes to a
select few of the updated pages.
Even though the Maven site structure and some of the pages it
generates are pretty much cast in stone, I don't think this is
necessarily a bad thing. Conformity is a cornerstone of usability so
if you've learned to navigage one Maven site, you'll have no trouble
navigating the Jackrabbit site. I also believe that we'll have more
flexibility with the site once we upgrade to Maven2.
> I am thinking of switching to plain Anakia for the site and using
> hand-crafted XML pages for project information. We can then manually
> publish the javadocs on a per-major-version basis.
> Are there any objections to that?
-0. In principle I'd be in favor of keeping the current Maven site,
but as long as the generated HTML needs to go through SVN this seems a
bit troublesome. How does the Maven project manage their site? I think
switching to a plain Anakia site would be a step back, but I won't
object if it's the only easy way to solve the problems mentioned
above.
> We need to update the README files. In particular, we should be
> giving credit to everyone whose work has made it into the product,
> whereas right now we only list the credits for the initial commit.
> Perhaps we should move that stuff to a CHANGES.txt file?
+1
BR,
Jukka Zitting
--
Yukatan - http://yukatan.fi/ - info@yukatan.fi
Software craftsmanship, JCR consulting, and Java development