tiles-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Mick Semb Wever <...@apache.org>
Subject Re: svnpubsub: migration plan
Date Thu, 27 Dec 2012 16:57:00 GMT

> > In other cases, like "wildcards documentation", documentation
> > enhancements come in that can be pushed immediately to staging. my
> > question what is best practice here?
> 
> If this is indeed the need, then I would gather all the documentation
> into a single maven project and separate it from the code itself.

I was also trying to highlight that there isn't just one need. That
there are two separate needs for documentation updates. Incompatible
changes related to new releases, and ongoing documentation improvements
based off the last release.

> > The way i see it must be done seems rather clumsy…
> > 1) checkout ^/framework/tags/tiles-parent-3.0.1/
> > 2) svn merge -rXXX ^/framework/trunk/src/site/apt/tutorial/advancedwildcard.apt
> > 3) mvn site:site
> > 4) cp target/site/tutorial/advanced/wildcard.html ../site/staging/framework/tutorial/advanced/wildcard.html
> > 4a) hack the snapshot header back to the release version
> > 5) svn ci ../site/staging/framework/tutorial/advanced/wildcard.html
> > 6) cast vote
> 
> This is basically the same process as the release of a project. 

Yes it is. And it seems a little superfluous to me. What highlights my
point is how we deal with http://svn.apache.org/repos/asf/tiles/site/

We make no releases of this code. eg there is no version number at the
top of these webpages. Any improvement there follows a simpler approach…

1) svn ci src/site/...
2) mvn site:site
3) cp target/site staging/  (maven-scm-publish-plugin removes this?)
4) svn ci staging
5) cast vote


I'm questioning the underlying reason of making releases and whether it
applies to documentation. Releases best solve the need for distributed
artifacts. Artifacts whom consumers take and use. The website, be it
static content or a dynamic application like a war file, is used by
others but is not "taken and used". We don't need to make releases of
such things and continuous deployment (CD) works. CD typically deals
with two branches: trunk and stable; where stable is pushed to
production.

I can see it to be easier if documentation follows the CD approach. This
permits for both use cases. Those incompatible doc changes don't get
push prematurely to the website because they are sitting in trunk. Quick
and compatible doc improvement can be pushed quickly out by "deploying"
them directly from our "stable branch" without having to make releases.
Our stable branch corresponds to the last release, eg
^/framework/branches/TILES_3_0_X/. And deploying documentation for us
means mvn site:site, maven-scm-publish-plugin, and casting a vote to
push staging to publish. 

If we are to go down this path then we should remove the version from
all webpages. The stable version is stated clear enough on the
frontpage.

~mck


-- 
“People only see what they're prepared to see.” - Ralph Waldo Emerson 

| http://github.com/finn-no | http://tech.finn.no |

Mime
View raw message