www-infrastructure-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Gav..." <ga...@16degrees.com.au>
Subject RE: CMS HowTo
Date Wed, 24 Nov 2010 02:58:03 GMT


> -----Original Message-----
> From: Marvin Humphrey [mailto:marvin@rectangular.com]
> Sent: Wednesday, 24 November 2010 12:20 PM
> To: infrastructure-dev@apache.org
> Subject: Re: CMS HowTo
> 
> On Wed, Nov 24, 2010 at 09:32:46AM +1000, Gav... wrote:
> > Feel free to go ahead with your CMS conversion. Create a Jira issue
> > initially for the first step.
> 
> Thank you, will do.
> 
> I imagine I missed something somewhere, but it wasn't apparent to me
> that
> opening a JIRA issue would be the first step to converting over...
> 
> And actually, it's not... I performed a JIRA search for "INFRA CMS";
> browsing
> some of the issues which came up was instructive.  The *first* step is
> to
> create a directory structure within SVN which conforms to the
> constraints
> described on the main CMS documentation page.  Without that, apparently
> the
> request cannot be processed (see
> <https://issues.apache.org/jira/browse/INFRA-3181>).

Well, however you want to read it, creating a jira issue is letting us know
that you intend to switch to the CMS, whether the directory structure comes
with it is a bonus.

> 
> It seems a little odd that a project must provide content before the
> CMS can
> be enabled.  I don't know markdown syntax; I'm going to be learning it
> as we
> go along.  Nevertheless, it's not hard to imagine technical constraints
> which
> make a conforming svn url a prerequisite for turning on staging, and of
> course
> infra has to rely on the project committers for that.
> 
> It really seems like there ought to be dummy site content somewhere for
> committers to use as a template.  If it's not practical to provide
> something
> within the ASF repository for committers to "svn copy", perhaps a
> tarball
> could work.
> 
> We now have the first steps for a "getting started" how-to:
> 
>   STEP 1: Create a conforming directory structure for the site content
> within
>           your project's repository.
> 
>     Obtain the template tarball from
>     <http://somewhere.apache.org/cms/template.tgz>.  Unpack it into a
> location
>     within your repository, e.g.
>     <https://svn.apache.org/repos/asf/myproject/site/> and commit it.
> Do not
>     change the layout or names of any of the files or directories
> within the
>     template.
> 
>   STEP 2: Ask Infrastructure to turn on staging.
> 
>     Open an INFRA issue and request that staging be turned on,
> providing the
>     svn url where you unpacked the dummy site template.
> 
>   STEP 3: Edit website content.
> 
>     The CMS uses "markdown" syntax...
> 
> > Read : http://wiki.apache.org/general/ApacheCms2010 which provides
> more
> > background and some examples (or links to).
> 
> According to that wiki page...
> 
>     http://www.apache.org/dev/cms.html is the reference documentation.
> 
> Is that really the role of the main cms page?  There's quite a lot of
> background historical material, prominently placed -- not what I would
> expect
> to find in "reference documentation".  It reads more like a proposal or
> a
> request for funding.
> 
> > Feel free during this process as you convert to add documentation to
> the
> > http://www.apache.org/dev/cms.html page as you feel would best help
> others
> > converting over - as a committer you have the rights to edit the
> page.
> 
> I don't feel like there's a place on that page for bootstrapping
> material as
> sketched out above -- the existing material is quite voluminous
> already, and
> has a different focus.  The "usage" material has been offloaded to a
> different
> page; however that "usage" page has already been claimed by infra for
> the
> specific documentation on how to update the infrastructure website.
> 
> IMO, there is no existing location which is suitable for adding
> committer-focused documentation.  It would be encroaching on either the
> historical rationale or the infra-specific materials.  It seems to me
> that
> either the focus of those pages should change (not my call to make) or
> a new
> page should be added.

So create a new page then, however you think you would like it to be
presented.

:)

Gav...

> 
> Best,
> 
> Marvin Humphrey
> 



Mime
View raw message