New Workflow

Both https://www.openoffice.org and this website - https://openoffice.apache.org are being moved to a new Git based process.

Workflow is described in the README files in each repository.

The Apache CMS is obsolete. Some of the workflow below might be useful and can be repurposed.

This documentation shows how to edit the Apache OpenOffice 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). When you edit a web page there are potentially four different versions of it to think about:

  1. There is the latest version of the page source stored in subversion.
  2. There is your working copy of that page source, which you are editing.
  3. There is the generated HTML from that source, in the staging directory.
  4. 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 the latest version of the web page's source.
  2. You edit the page source using Markdown text syntax (mdtext).
  3. You commit the source into the repository. (You will see the SVN commit mail with your log message.)
  4. 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 message.)
  5. 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 " 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.

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

Edit the file via your favorite editor like vi and finally commit via SVN:

 vi myfile.mdtext
 svn ci -m"My log message" myfile.mdtext

Now wait a few seconds so that the entire website can be rebuilt. Verify the staged webpage in a web browser at:

 http://openofficeorg.staging.apache.org/openofficeorg/myfile.html

Then publish the site:

curl -sL http://s.apache.org/cms-cli | perl

If this does not work on your local machine just do it on "people.apache.org" by executing this:

ssh -t <user>@people.apache.org publish.pl openofficeorg <your Apache ID>

Browser-based editing workflow

Prerequisites

Browser bookmark

Normally you see the webpage in your browser. To update this page with an inline-editor and little preview you use the Apache CMS JavaScript bookmarklet. Drag that link to your browser's toolbar. For more information see here.

Apache ID

Furthermore, you need an Apache ID to authenticate to the system.

Starting

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

Click on the actions link [Edit] in the appropriate table cell for editing the 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 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.

When you have finished writing your text, check the "Quick Commit" box, enter a 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. 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.

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

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

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]. Generally speaking it is always a good idea to use the CMS to delete files and directories over using the command-line svn interface, as the CMS will ensure everything gets deleted from the staging (and eventually production) repository on commit. If you use the command- line interface instead, you will also need to manually delete the corresponding entities in the staging repository in order for those changes to propagate to the production site.

CMS Documentation Reference