incubator-ooo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Dennis E. Hamilton" <>
Subject Give Me a C, Give me an R, CTR! The Incubator OpenOffice Web Site
Date Sun, 26 Jun 2011 00:52:32 GMT
Thanks to the efforts of marcus, therabi and others, the incubator web site is taking form:
<>.  This is separate from the two wikis. 
It is complementary to the wikis.

We have committers (give me a "C") working on the site, as you can see if you subscribe to
or take a peek at  The archive is at <>
and you can also subscribe to it in RSS (Atom 1.0) if you don't want to use an e-mail list.
 (You can also read the latest commits in your browser.  I notice that it can be a little
easier reading the Atom rendering than the plaintext e-mail.)

There's more below:

	1. Now Is the Time for Review and Improvement
	2. What You Need To Know - Going Deep
	3. What You Need to Know To Contribute - Starting Easy, Learning the Ropes
	   3.1 The simplest contribution: e-mail to the list
	   3.2 More formality, better tracking: bug reports/requests
	   3.3 Develop a patch
	4. Wait, There's More!

 - Dennis


Now is the time for "Then Review" (CTR!).  This is how evolution of development and Lazy Consensus
go together.  (See <>.)

Anyone subscribed to ooo-dev can contribute review and changes of the web site. Anyone.  There
are some things to understand first.


The web site is not authored in HTML and you can't post directly to the site.  

 * The web site is authored in the incubator SVN.

is the SVN folder corresponding to the root folder of the site, 

 * The web site is authored using a special text language, MarkDown. 
<> is the "official" guide.
<> is more information on
our own site.

 * The markdown pages have extension .mdtext in the SVN.  The corresponding page on the site
will have extension .html.  

 * There are other things to know, such as where images go, where the stylesheets are, and
even deeper things in the workings of the web site.  You don't need to know all of that to
be a contributor.


(I have no idea where "learning the ropes" comes from.  What is the expression in your part
of the world?)

 3.1. The simplest contribution: E-mail to the list

Notice something that needs correction and contribute it via an e-mail.  Just text, not a
patch.  To make sure it is noticed, the subject line is important.  I don't know if there
is a convention.  But something like [COMMENT] or [EDIT] and enough identification of what
your commenting on or proposing an edit to might do the job.

 3.2. More formality, better tracking: Bug Reports/Requests

We haven't settled on a bug/issue reporting and tracking mechanism yet.  When that's all sorted
out, this is another way.

 3.3 Develop a Patch 

Patches can be submitted in E-mail or in a bug/incident notice (when we are ready for those).
 Patches have a particular technical format.

This will involve obtaining a copy of the MarkDown page(s), making a modified copy, and deriving
a patch file on your computer.  That patch e-mail should probably have [PATCH] in the subject
and enough description so a reader can tell what it is you propose to patch.

If you run Subversion on your own computer, you can use it to have a working copy of the site
Markdown locally.  You can learn a lot about Markdown just comparing the .mdtext pages with
the web pages that correspond to them.

If you do have a Subversion-obtained working copy, there are accompanying tools for making
a patch in the format that we require.  Software like TortoiseSVN and svn-workbench make working
with Subversion via GUI interfaces much easier.


There is a publishing workflow that operates between the SVN repository for the site and the
place where the finished pages are served to users through their web browsers.

As a contributor, you don't have to worry about that.  But it is useful to understand what
the delays you may notice are all about.  Here's effectively what happens:

The first stage takes the markdown and transforms it to web pages in what is called the staging
site.  (This is where we can see if there is something that is not quite right.)

After that, if all goes well, pages on the staging site move to a set of folders that are
the production site.  It is the production site that you see in your browser.

Although there's more learning curve than posting on a blog, or a wiki, or on your own web
site, perhaps this reveals why SVN is so important in the work processes of Apache projects.
 They provide both accountability, transparency, and a way to recover from misadventures.
 And that is why there is little to fear of Commit then Review, so long as Review actually

 		*** end ***


View raw message