Skip to end of metadata
Go to start of metadata

Rotating the documentation wiki spaces

One of the last steps in the QA process involves "rotating" the documentation wiki spaces. "Rotating", in this sense, means reassigning or copying the DOC and UNRELEASED wiki spaces to point to, respectively, the just released version and the upcoming version, respectively.

This can be best explained in a working example.

Say the QA process for version 5.0 is wrapping up. Until now, 4.5 has been the current version. This means that the DOC wiki space currently refers to 4.5, and the UNRELEASED wiki space refers to the as-yet-to-be released 5.0.

In this example, we currently have these spaces:

  • DOC -> 4.5
  • UNRELEASED -> 5.0

We now want 5.0 to be the newest current version and hence the DOC wiki space should reflect that version. This also means 5.1 should become the next upcoming version, and hence the UNRELEASED documentation should now be available for editing, to reflect upcoming changes in that version. There are three steps for this to happen, and these steps must be performed in this exact order:

Icon

The specific commands listed below may have changed beginning with Confluence version 5.0, which made extensive changes to wiki administration-related pages. (We are using Confluence version 5.4.3, as of this writing; see the footer at the bottom of each wiki page for the currently installed version.)

 

  1. COPY the DOC space and name the new space CollectionSpace 4.5 Documentation with a space key of CSPACE45
    • Log in to the Confluence wiki, if you haven't already done so.
    • Visit any page on the DOC wiki. Verify that DOC appears in the URL.
    • From the Browse menu, select Space Admin

      Icon

      You will need Space Admin privileges to see the Space Admin option in the Browse menu. If you have been granted those privileges and don't see that option, refresh the page; if you still don't see it, clear browser caches, then refresh the page once again.

    • From the left sidebar, under General, click Copy Space
    • Verify that key=DOC appears in the URL.
      As noted above, name the new space CollectionSpace 4.5 Documentation with a space key of CSPACE45 (Our naming convention for the "space key" - a unique identifier for each wiki space, used internally by Confluence - is CSPACE + release number without spaces.)

      Icon

      Check to make sure that a wiki space with your chosen space key doesn't already exist. (If it does, you'll encounter a Confluence system error when trying to create a new space with that same space key.)

      To verify this, visit: http://wiki.collectionspace.org/display/{your_chosen_space_key_here}/

      For instance, to make sure that the CSPACE45 space key doesn't exist, visit: http://wiki.collectionspace.org/display/CSPACE45

    • Enable Use existing authors and dates, if that option is not yet enabled.
    • Enable Copy personal labels, if that option is not yet enabled
    • Follow the onscreen prompts to finish copying the space. This can take a considerable length of time (up to 30 minutes), so please be patient.

      When will the copy be finished?

      Icon
      It is very likely the web browser you're using to initiate the copy will time out and put up an error. If you have an system account on wiki.collectionspace.org, you can check to see if the Copy is finished by running the Linux "top" command.  In the list of top processes, look for the row with the user named "confluence". Once the CPU percentage of that row drops below ~10%, the copy should be complete.
    • Verify that the new space (in this example, CollectionSpace 4.5 Documentation) exists, and that it has the same content as the current DOC space:

      • From the Spaces menu, select Space Directory
      • Find and click the link for your newly-created space (named, in this example, CollectionSpace 4.5 Documentation)

  2. DELETE the current DOC space
    • Visit any page on the DOC wiki. Verify that DOC appears in the URL.
    • From the Browse menu, select Space Admin
    • From the left sidebar, under General, click Delete Space.
    • Follow the onscreen prompts to finish removing the space. This can take a considerable length of time, so please be patient.
    • Verify that the DOC space has been removed:
      • From the Browse menu, select Space Directory
      • Make sure that there is no space named CollectionSpace Current Documentation
      • Attempt to visit the following URL and doubly make sure this wiki space no longer exists:
        http://wiki.collectionspace.org/display/DOC
      Icon

      If after the Delete Space operation completed, Confluence then reported that this wiki space was completely deleted, but you still see it in the Space Directory and/or when visiting its URL, it's possible that you're viewing cached data on the server. To fix this, follow the instructions on the Wikis page to restart the Confluence wiki server.


  3. COPY the UNRELEASED space and name the new space CollectionSpace Current Documentation with a space key of DOC
    • Visit any page on the UNRELEASED wiki. Verify that UNRELEASED appears in the URL.
    • From the Browse menu, select Space Admin
    • From the left sidebar, under General, click Copy Space.
    • As noted above, name the new space CollectionSpace Current Documentation with a space key of DOC
    • Enable Use existing authors and dates, if that option is not yet enabled.
    • Enable Copy personal labels, if that option is not yet enabled
    • Follow the onscreen prompts to finish copying the space. This can take a considerable length of time (up to 30 minutes), so please be patient.

      When is the copy finished?

      Icon

      It is very likely the web browser you're using to initiate the copy will time out and put up an error. If you have an system account on wiki.collectionspace.org, you can check to see if the Copy is finished by running the Linux "top" command.  In the list of top processes, look for the row with the user named "confluence". Once the CPU percentage of that row drops below ~10%, the copy should be complete.

    • Verify that the newly re-created space, CollectionSpace Current Documentation, exists, and that it has the same content as the UNRELEASED space:
      • From the Browse menu, select Space Directory
        1. Find and click the link for your newly re-created space named CollectionSpace Current Documentation

  4. RESTART the wiki by following the instructions on the Wikis page to restart the Confluence wiki server

After rotating the spaces (in this example) you should now have these wiki spaces:

  • CSPACE45 -> 4.5
  • DOC -> 5.0
  • UNRELEASED -> 5.1
  • CollectionSpace 4.5 (CSPACE45) contains the previous version 4.5 documentation.
  • CollectionSpace Current Documentation (DOC) contains the current version 5.0 documentation.
  • UNRELEASED (UNRELEASED) derived from the current version 5.0 documentation, and is available for updating to reflect changes in the next version, 5.1

Post-rotation updating

Updating the navigation (left sidebar) and header for each new space

Icon

The specific commands listed below may change beginning with a future Confluence version, if what is currently the Documentation Theme is merged into the default theme or is otherwise materially changed. (We are using Confluence version 5.4.3, as of this writing; see the footer at the bottom of each wiki page for the currently installed version.)

Some updating is required once the two wiki spaces from the above process have been created (or in the case of the DOC wiki, re-created). A newly-created wiki space lacks our customizations to two important sections we utilize for documentation: Navigation (in the left sidebar) and Header. Each of these areas is configured under the Space Admin panel.

You will perform these updates for each new wiki space, which you created by copying an existing wiki space. (In the examples given here, you will need to complete the steps below for the CollectionSpace 4.5 Documentation (CSPACE45) and CollectionSpace Current Documentation (DOC) wiki spaces, both of which you created by copying them from other wiki spaces.)

  • Go to the relevant wiki space. (One way to do so is by going to the Browse menu, and selecting Space Directory)
  • From with the Space Admin panel, click the Themes menu option (listed under Look and Feel, near the bottom of the left sidebar).
  • The default theme should be the Documentation Theme. Click the Configure Theme link listed there.

On the Documentation Theme Configuration page, there will be two sections: Navigation and Messages.

Navigation section
  1. For Navigation make sure the two check boxes are marked:
    • Page tree
    • Limit search results to the current space
  2. Enter the following into the Navigation text box, for both the previous release's space (in this example, CSPACE45) and the DOC space:

Messages section
  1. Enter the following into the Header text box:
    • For the previous release's space (in this example, CSPACE45):

    • For the DOC space:

Click Save at the bottom of the Theme Configuration page, to save your changes to the Navigation and Messages sections.

Updating the custom stylesheet for each new space

A newly-created wiki space also lacks our custom CSS stylesheet. This is also configured under the Space Admin panel. Among its effects, this stylesheet ensures that the CollectionSpace logo in the page headers isn't distorted by being squeezed into a too-small space.

You will perform this update for each new wiki space, which you created by copying an existing wiki space. (In the examples given here, you will need to complete the steps below for the CollectionSpace 4.5 Documentation (CSPACE45) and CollectionSpace Current Documentation (DOC) wiki spaces, both of which you created by copying them from other wiki spaces.)

  • Go to the relevant wiki space. (One way to do so is by going to the Browse menu, and selecting Space Directory)
  • From the Browse menu, select Space Admin
  • From the left sidebar, under LOOK AND FEEL, click Stylesheet
  • If the Stylesheet shown on this page is empty:
    • Click Edit
    • Paste in the following text:

    • Click Save

Updating the version for the UNRELEASED space

  1. Visit the UNRELEASED wiki
  2. Search for a page named VERSION
  3. Visit and edit that page
  4. Update that page to the next version of CollectionSpace; e.g. in this example, 5.1 (This page's contents should consist only of a version number, with no other text present on that page.)
  5. Save the changed page

Updating the versions sidebar page for the UNRELEASED space

The VERSIONS SIDEBAR is maintained within the UNRELEASED wiki space, and is then referenced (included) from other wiki spaces. To update that page:

  • Visit the VERSIONS SIDEBAR page; e.g. at http://wiki.collectionspace.org/display/UNRELEASED/VERSIONS+SIDEBAR
  • Edit the page.
  • Change and/or add to the three top-most entries in that sidebar to reflect the currently available wiki spaces: In the rotation scenario discussed in this document, those entries would look much like this:

    (The first line should always link to the wiki space with the space key of UNRELEASED, the second line should always link to the wiki space with the space key of DOC, and the third line - which you'll need to add - should always link to the newly-created wiki space for the immediately previous version: the one that has been replaced by your newly-launched, current version, referenced by DOC.)

  • Save your changes.

Updating the DOC space

On the DOC space, these are some of the changes that should be made (or at least reviewed for possible change):

  1. The VERSION INCLUSIONS page should be updated with the name of the current version's tarball file, and any other needed changes. Doing so will automatically update relevant text on several of the installation guides, via the magic of something like an 'include' (Page Include) or 'multi-excerpt-include' (Multi-Excerpt) macro.
  2. The CollectionSpace Release Documentation page should be checked to ensure that the relevant version number(s) are updated, to point to release notes for the current version, and that these link(s) go to the correct pages.
  3. The System Requirements page should be reviewed, and edited as needed.
  4. Installation guide pages should be edited, as needed. Any warning blocks at the top of these pages should be reviewed, and edited or removed as needed.
Icon

The changes mentioned above - and possibly other changes, as well - might potentially be covered in another document. If so, we should consolidate those changes as needed.