User:Aeric/Writing and Publishing Guide

Important: This page has been updated as of Jan, 2014. Other guide pages may be out of date.

Release Model

• Dated Cloud Releases

• The platform running in the cloud is updated at 2, 3, or 4 week intervals.
• When an update occurs, the features previously regarded as "Coming Soon" are added to the Release Notes, with a date to indicate when the update occurred.

• Versioned ISV Releases

• When a new "installable version" is released, a snapshot of the cloud wiki is taken.
• The snamsphot is given a version number.
• The help link in the installable version points to that wiki so that, as features evolve in the cloud, accurate help remains available for the installable version.

• Wikis

• lj_wiki -- LongJump wiki in the cloud
• lj{v#} (ex: lj100) -- Versioned LJ ISV wiki
• aa_dev (to be renamed. currently mw_dev) -- pre-release AA wiki
• aa_wiki (to be renamed. currently mw_prod) -- AA wiki in the cloud
• aa(v#} (ex: aa100) -- Versioned AA ISV wiki

Note: A two-digit version number would probably be sufficient. The extra digit is included in case a intermediate versioned release is needed--for example: 10.1. But that circumstance may never occur. So lj10 and aa10 would be simpler--and lj101 could always be created, if needed.)

• Help Links

• The help link in the cloud points to the appropriate wiki:

• AgileApps ==> http://agileappslive.info/wiki, which references the aa_wiki.
• LongJump ==> http://lj.platformatyourservice.com/wiki, which references lj_wiki.

• Help links in the installable versions point to a versioned wiki:

• AgileApps ==> http://agileappslive.info/aa100 (for example)
• LongJump ==> http://isv.platformatyourservice.com/lj100 (for example)

(Note that the "isv" subdomain is used for the versioned wiki, to activate the "whitelabel" skin.

Procedures

The procedure to use depends on the type of activity and the target of that activity (i.e., the product it applies to).

Activity	AgileApps	LongJump
Critical Bug Fix (feature not usable)	Fix AA dev wiki (mw_dev) Fix AA cloud wiki (mw_prod) Fix current ISV wiki (aa###)	Fix LJ cloud wiki (lj_wiki) Fix current LJ ISV wiki (lj###)
Cosmetic Fix (typos, wording, better text)	Modify the AA Dev wiki page. (Changes will migrate at next dated release.)	When an equivalent AA page is reorganized: Reflect the reorg in the LJ wiki to ensure that future changes can be made without difficulty. Skip all other "cosmetic" improvements.
New Platform Feature	Add to Dev wiki http://agileappslive.info/mw_dev Add a Coming Soon entry, with a Learn More link: http://agileappslive.info/mw_dev/Coming_Soon Review the entry with SMEs When good, copy blurb to cloud, without the link: http://agileappslive.info/wiki/Release_Notes	If feature is in AA wiki, get release notes blurb and docs reviewed there, first. Add docs to the LJ cloud wiki: http://lj.platformatyourservice.com/lj_wiki Add entry to "Coming Soon" section at top of Release Notes: http://lj.platformatyourservice.com/lj_wiki/Release_Notes Include link to the doc page Note: There is no "pre-release" wiki. Installations point to a versioned wiki, so they're good. Cloud users may see a future item, but for only a few weeks at most. (Fewer LJ users are scanning the Wiki than the AA wiki. SE's in the field are scouring that one.)
Dated Cloud Release	First release: Convert Release Notes page from redirect to dated listing Move features from Coming Soon page to Release Notes page Activate "check back" text on Coming Soon page, unless future features remain)	First release: Convert Release Notes page from redirect to dated listing Move features from Coming Soon page to Release Notes page Activate "check back" text on Coming Soon page, unless future features remain)
New ISV Feature or Installation Note	First change: Remove redirect on ISV Release Notes page {[subst: ISV Release Notes}} or copy most recent version Document the feature Add link to ISV Release Notes ISV Release Notes	First change: Remove redirect on ISV Release Notes page {[subst: ISV Release Notes}} or copy most recent version {[subst: ISV Release Notes}} or copy most recent version Document the feature Add link to ISV Release Notes
Versioned ISV Release	In AA Dev wiki: Move "Release Notes" page to "Version ## Platform" Activate the redirect on the release notes page Change the link that goes to the earlier-version release notes at the top of the page Move to ISV Release Notes to Version ##.# Installable, leaving a redirect Regenerate and re-post Javadocs to dev wiki (Does not apply to LJ, due to AA-specific APIs. E.g accessProfile.) Modify readme to correct links for the listing on the SAG "Empower" page (HTML format). file: work/AgileAppsReadme.html (put under source control) Modify links and send Steve O'Brien (or Uday) for uploading To view an existing page, follow the instructions in the README file	Move "ISV Release Notes" page to "Version ## Installable", leaving a redirect

Publishing the AA Dev Wiki

First, prepare the development wiki for publication. Then execute the publishing process.

Preparation:

• Find and fix all transclusions of Template:TBD
• In the dev wiki, change the Coming Soon heading to reflect the release date.
  http://agileappslive.com/mw_dev/Platform_Features
• Leave unimplemented entries under Coming Soon or, if there are none, comment out that section

Publication:

1. Using PuTTY, log in to the Rackspace server
2. Run scripts/publishDevWiki to copy the contents of the
   development wiki (mw_dev) to the production wiki mw_prod

   This process makes a backup of the production wiki.

   If there is ever any need to revert to a previous version,
   run scripts/restoreWikiInstructions for a list of steps