incubator-ooo-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From robw...@apache.org
Subject svn commit: r1141265 - /incubator/ooo/site/trunk/content/openofficeorg/docs/edit-cms.mdtext
Date Wed, 29 Jun 2011 21:52:20 GMT
Author: robweir
Date: Wed Jun 29 21:52:19 2011
New Revision: 1141265

URL: http://svn.apache.org/viewvc?rev=1141265&view=rev
Log:
Added more detailed steps on the web interface

Modified:
    incubator/ooo/site/trunk/content/openofficeorg/docs/edit-cms.mdtext

Modified: incubator/ooo/site/trunk/content/openofficeorg/docs/edit-cms.mdtext
URL: http://svn.apache.org/viewvc/incubator/ooo/site/trunk/content/openofficeorg/docs/edit-cms.mdtext?rev=1141265&r1=1141264&r2=1141265&view=diff
==============================================================================
--- incubator/ooo/site/trunk/content/openofficeorg/docs/edit-cms.mdtext (original)
+++ incubator/ooo/site/trunk/content/openofficeorg/docs/edit-cms.mdtext Wed Jun 29 21:52:19
2011
@@ -16,27 +16,38 @@ Notice:    Licensed to the Apache Softwa
            specific language governing permissions and limitations
            under the License.
 
-This HowTo documentation will show the needed steps to edit the Apache OpenOffice.org
+This documentation shows how to edit the Apache OpenOffice.org
 website. This includes creation of new pages, modification, and deletion - for files
 and sub-directories.
 
 ## How it works in general
 
-The website is hosted in a Content Management System (CMS). You will not edit the
-HTML pages directly. The actual edit is split into two steps:
+The website is hosted in a Content Management System (CMS). When you edit a web page
+there are potentially four different versions of it to think about:
 
- 1. First you edit the content which is provided as [Markdown text][1] (mdtext).
-    This will be committed into the staging section (see the SVN commit mail with
-    your log message) and automatically build HTML files out of the the mdtext files
-    (see the commit mail with "Staging update by buildbot" as log messge).
+ 1. There is latest version of the page source stored in subversion.
+ 1. There is your working copy of that page source, which you are editing.
+ 1. There is the generated HTML from that source, in the staging directory.
+ 1. There is the production version of the HTML, which is what the public sees.
+
+
+The general flow for updating the website is:
+
+ 1. You check out latest version of the web pages source.
+ 1. You edit the page source using [Markdown text syntax][1] (mdtext).
+ 1. You commit the source into the repository.  You will see the SVN commit mail with
+    your log message
+ 1. The commit automatically triggers a build that converts the markdown files 
+into HTML files in the staging directory.  You will see a commit mail with "Staging update
by buildbot" as log messge).
+ 1. You verify that the staged webpage is correct and then tell the CMS to publish 
+the changes to the production directory.  (You will see a commit mail with "Publishing merge
to openofficeorg site by <your Apache ID>"
+    as log message.)
+
+The intent of this workflow is to allow committers flexibility in changing 
+webpages and testing changes on a staging website, before moving these changes to
+the public web site.
 
- 2. Second you need to publish the staging part to the production section (see the
-    commit mail with "Publishing merge to openofficeorg site by <your Apache ID>"
-    as log message).
-
-## What do you prefer: Working via command line or in the browser?
-
-### Via command line
+## Command line editing workflow
 
 It is assumed that you have already checked out the code from the SVN repository
 (https://svn.apache.org/repos/asf/incubator/ooo).
@@ -55,66 +66,82 @@ executing this:
 
     ssh -t <user>@people.apache.org publish.pl openofficeorg <your Apache ID>
 
-### Editing in the browser
+## Browser-based editing workflow
 
-#### Prerequisites
+### Prerequisites
 
-##### Browser bookmark
+#### Browser bookmark
 
 Normally you see the webpage in your browser. To update this page with an
-inline-editor and little preview you need to add a link as bookmark to your browser
-(more information see [here][2]).
+inline-editor and little preview you use the [Apache CMS] [3] JavaScript bookmarklet.  Drag
that 
+link to your browser's toolbar.  For more information see [here][2].
 
-Drag this [Apache CMS] [3] bookmarklet to your browser's toolbar.
-
-##### Apache ID
+#### Apache ID
 
 Furthermore, you need an Apache ID to authenticate to the system.
 
-#### Starting
+### Starting
 
-Browse to the respective webpage or directory you would like to edit and click on
-the bookmark. Now click on the [Edit this directory] link on the top. The following
+Browse to the webpage or directory you would like to edit and click on
+the bookmarklet. Now click on the [Edit this directory] link on the top. The following
 is displayed as content from the CMS.
 
-#### Edit an existing webpage
+### Edit an existing webpage
 
 Click on the actions link [Edit] in the appropriate table cell for editing the
-favorite file. If the file is not in this directory but in a subdir, just click on
+current file. If the file is not in this directory but in a subdirectory, just click on
 the directory name (e.g., "docs/") to enter this directory.
 
-Now you should see a new webpage with a 4 fields:
+Now you should see a new webpage with four fields:
 
  1. Upper left is the inline editor for text in markdown syntax.
- 2. Upper right shows the written text as a permanent preview or as HTML source code.
- 3. Below the editor you can enter a log message.
- 4. Enter a general header text, e.g., the license of the entered text.
+ 1. Upper right shows the written text as a permanent preview or as HTML source code.
+ 1. Below the editor you can enter a log message.
+ 1. Enter a general header text, e.g., the license of the entered text.
 
 When you have finished writing your text, check the "Log message" box, enter a
-commit message and click on [Submit].
+commit message and click on [Submit].  This commits your changes to the Subversion 
+repository.
+
+### Verifying the staged web site
+
+As noted above, committing your changes triggers a build of the markdown files
+into HTML in the staging directory.  This could take 15-30 seconds.  So wait a few
+seconds and then click the [Staged] link to view your web page as staged.
+
+At this point you should test your web page.  Does it look right?  Any spelling 
+errors? Do the links work?  If you've made substantial changes, perhaps test in
+more than one browser.
+
+Once you are satisfied that the page is correct, you are ready to publish it
+to the production site.
 
-#### Create a new webpage
+### Publishing to the production directory
+
+After you have edited your files and/or directories, you need now to publish your
+modifications into production. For this please click on the link
+[Publish site] on the top of the webpage. Enter a commit message on click 
+on [Submit].  After a few seconds you can check the [Production] link to see the
+live version of your changes.  
+
+
+### Create a new webpage
 
 When in the correct directory, at the top enter a name for the new text file (e.g.,
 "my-file.mdtext"). Now you enter your text (see topic above).
 
-#### Create new subdirectory
+### Create new subdirectory
 
 When in the correct directory, at the top enter a name for the new directory (e.g.,
 "my-dir/"). Make sure you entered a trailing "/"!
 
-#### Delete a webpage or subdirectory
+### Delete a webpage or subdirectory
 
 When in the correct directory, click on the actions link [Delete] in the appropriate
 table cell and enter a commit message. Finally click on [Submit].
 
-#### How to put into production?
-
-After you have edited your files and/or directories, you need now to pubish your
-modifications into production. For this please click on the link
-[Publish site] on the top of the webpage. Enter a commit message on click on [Submit].
 
-### Links
+## Links
 
 [CMS Documentation Reference][4]
 



Mime
View raw message