Mailing-List: contact infrastructure-dev-help@apache.org; run by ezmlm
Precedence: bulk
Reply-To: infrastructure-dev@apache.org
Received-SPF: pass (athena.apache.org: local policy)
Date: Tue, 23 Nov 2010 18:19:46 -0800
To: infrastructure-dev@apache.org
Subject: Re: CMS HowTo
Message-ID: <20101124021946.GA19268@rectangular.com>
References: <4CEC141C.2090409@eventful.com>
 <000301cb8b66$bc512270$34f36750$@com.au>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <000301cb8b66$bc512270$34f36750$@com.au>
User-Agent: Mutt/1.5.13 (2006-08-11)
From: Marvin Humphrey <marvin@rectangular.com>

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>).

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.

Best,

Marvin Humphrey