I was mesmerized by the abundance of resources for new Apache Software Foundation (ASF) committers. As a result of this bounty, it took more time than I expected to make my initial commit. The process now seems straightforward, but way back, say, 24 hours ago, things were much fuzzier.

Two resources are key. If you’ve watched Rob Weir’s video tutorial and read the Get Started Editing a Page link in the CMS Reference, good for you! You are ahead of where I was. These references are probably good enough for most people, although one important point is missing: The copy I was editing did not match the live web page. I needed to update my local version before editing, which sounds obvious now, but that’s because I finally understand how the process works.

After successfully publishing a couple of minor commits, I gathered the relevant reference information along with tips from my fellow committers. The result is this step-by-step procedure. As I am a new committer myself, there are likely things I have yet to understand or am explaining poorly. Please feel free to question, correct, or comment for the benefit of all new committers.

Before your first edit

Drag the ASF CMS bookmarklet to your browser’s bookmarks bar. This component allows you instantly to edit a live Apache CMS webpage.

How the process works

There are three environments (Local, Staged, and Production) and five steps in the editing and publishing process. Understanding the steps and environments can help you interpret unexpected results. (For example, the case when my Local copy was different from the Production version.) The general flow is as follows:

→ Update your Local version (associated with your Apache account).

→ Edit your Local version.

→ Commit changes to a Staged version.

→ Review changes in the Staged version.

→ Publish changes to the Production version.

Update Local Version

1. Navigate to the live (aka Production) version of a web page.
2. Click on the ASF CMS bookmarklet (see Prerequisites, above).
   • Initially, you will be prompted to enter your @apache.org id and password.
   • The page title will be Browse {ProjectName}.
   • Notice the six links above the word Content:
[Update] [Edit] [Static] [Staged] [Publish Site] [Production].
3. Click on [Update].
4. Next, click on the Update This Resource button.
   
5. You should see an Update complete message.
   

Edit Local Version

1. Notice the three links at the bottom of the Update complete message:
   [Edit] [Browse] [Diff].
2. Click on [Edit].
3. The page title will be Edit File: {ProjectName} .
   
4. Make changes to this file.

Commit Changes to Staged Version

1. Click the Quick Commit check box below the content you just edited.(Note: a quick commit bypasses the staged build.) 
2. Enter commit message in Log message text box.
3. Click the Submit button.
4. You should see a Commit successful message.

Review Changes in Staged Version

1. Notice the six links at the bottom of the message:
   [Follow Staging Build] [Staged][Publish Site] [Production] [Browse] [Edit].
2. Click on [Staged] to review Staged version and make sure everything looks good.
3. Return to editing view using browser’s back button.
4. If you don’t see your changes, click on [Follow Staging Build], and make sure there are no active builds.
   

Publish Changes to Production Version

1. In the editing view, click on [Publish Site]. You will see a screen that says something like Publish incubator site.
2. Before publishing, click on [View Diff], below the submit button, and verify the changes are correct.
   
3. Click on the Submit button.
   • You should get a success message: “Congratulations, ____! You’ve published the ______ website.” 
   • From here you can view the Production version, Browse files, or make additional Edits.

Wrap Up

This post offers a first draft procedure, aimed at new and not-very-experienced committers, and is not an authoritative treatise on editing ASF CMS webpages. As such, there are concepts I do not thoroughly understand and have therefore not explained. I encourage you to add comments to clarify and correct any errors, and I will do the same as my experience grows.

Still, this procedure does what I intended: It documents the steps I need to remember for updating an ASF webpage. I won’t need them tomorrow, but someday I know I will appreciate the refresher. I hope it helps you, too.