User:Aeric/Writing and Publishing Guide

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

Standard Tasks

• As new release dates are announced in meetings, add them to the list of Upcoming Releases
• Get information on new features from developers

How to Do Stuff

• Many things are accomplished using the Wiki Templates. Browse them to see what they do:

• Sidebar > toolbox > Special Pages > All Pages
• Namespace: template
• [Go]

Of particular interest:

• Template:Cheatsheet -- usage instructions for some useful templates that have similar names
• Template:Variables -- a listing of variables defined in LocalSettings, and their values in the current skin

• Also see User:Aeric/tests for interesting bits of wiki lore and examples of how to do things.
• This file contains snippets of wiki code: MediaWiki_Notes.txt

• I inherited a similar file, but it was too large to use.
• So I started one of my own, accumulating tidbits as I learned them or found them in the wiki.
• It started out small, and was very handy.
• Over time, though, it grew too large for anyone else to use!
• So you're encouraged to collect your own set of notes, unless you happen to be able to make sense out of that one.

--eric

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 dev wiki is taken.
• The snapshot 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 (now down-rev) installed platform.

• For the cloud release: publishDevWiki
• For the ISV release: versionAgileAppsDevWiki
• On rare occasion when things have been added to dev wiki that are not included in ISV release:

versionAgileAppsProductionWiki

Note: Releases are currently staggered, with cloud releases at end of month, and ISV releases 2 or 3 times a year in the middle of the month. At those times, some new features go into into the ISV release before they are seen in the cloud.

• Wikis

• ljwiki -- LongJump wiki in the cloud
• lj{###} -- Versioned LJ ISV wiki (ex: lj100)
• aadev -- pre-release AA wiki
• aawiki -- AA wiki in the cloud
• aa(###} -- Versioned AA ISV wiki (ex: aa100)

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://agileappscloud.info/wiki, which references the aa_wiki.
• LongJump ==> http://lj.platformatyourservice.com/wiki, which references ljwiki.

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

• AgileApps ==> http://agileappscloud.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.

Ordering Tasks

These are the possible values for the doc task fields. At the moment, they map imperfectly to the manual procedures outlined below:

• Target - which version of the platform is affected.
  (Selects the column in the manual procedures)

• AA Only - Applies to AgileAppsLive only
• LJ Only - Applies to LongJump only
• AA & LJ - Applies to both AgileApps and LongJump

• Audience - This setting creates a partitioning into sets of things that are related to each other.
  (The most important partition is at the top. Others come in the order shown.)

• User-Designer - For docs read by users, sys admins, and/or application designers.

--This is really an audience designation. Separating into the 3 different kinds would be good.

• API-Dev - An API change or feature that affects developers.

--Another audience designation, for the 4th kind of reader.

• Code - Generally an enhancement request that contains a code sample to include.

--In terms of a full matrix, it's audience=Developer, doc type=Enhancement.

• Install - An installable version feature or installation note.

--Audiencetype #5: Installer. Could be a feature, enhancement, cosmetic fix, or bug fix.

Merging the audience settings above with the activities below is tricky.

• For example, the "ISV feature" activity below is just audience=Installer, activity=New Feature.
• BUT, in terms of prioritizing, ISV features only become important when an ISV Release is near.
• So the order in which things need to be addressed is actually a partial-ordering that is produced by a set of compound conditions:

If target=AA Only or target=AA and LJ:

activity \ audience:	User	Designer	Sys Admin	Developer	Installer
Bug Fix	10	12	14	16	18
Cosmetic Fix	20	24	30	34	62
New Feature	22	26	32	36	64
Enhancement					68
Release	50				70
Doc Enhancement	90	92	94	96

If target=LJ Only:

activity \ audience:	User	Designer	Sys Admin	Developer	Installer
Bug Fix	10	12	14	16	18
Cosmetic Fix					62
New Feature	22	26	32	36	64
Doc Enhancement					68
Release	50				70
Cosmetic Fix	80	82	84	86
Enhancement	90	92	94	96

Notes:

• Rules should be applied on record update only when ISCHANGED is true for one of the independent fields in the ordering equation (activity, audience, or target), using the expression:

OR(ISCHANGED(activity_766224774), OR(ISCHANGED(target_766224774), ISCHANGED(doc_type_766224774)))

where doc_type_766224774 is the audience field

• They should also execute only when all three fields are non-empty, using the expression:

NOT(OR(ISNULL(target_766224774), OR(ISNULL(activity_766224774), ISNULL(doc_type_766224774))))

• The ordering values create priority-partitions. Within each partition, the order is AA, then AA/LJ, and then LJ--primarily to keep similar kinds of tasks together.

• The tricky bit is that the priority matrix changes as a release draws near. So, for a complete ordering that reflects current circumstances, there should be multiple priority matrixes, with the ability to choose the one that is currently in effect. (But the need for that feature evaporates if the task list can be kept short.)

Manual Procedures

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

Bug Fix

(P1=feature not usable)

AgileApps	LongJump
Fix AA dev wiki (aadev) Fix AA cloud wiki (aawiki) Fix current ISV wiki (aa###)	Fix LJ cloud wiki (ljwiki) Fix current LJ ISV wiki (lj###)

Cosmetic Fix

(typos, wording, better text)

AgileApps	LongJump
Modify the AA Dev wiki. (Changes will migrate at next dated release.)	Skip small "cosmetic" improvements.

Enhancement

(New page, vastly improved page, PDF article update.)

AgileApps	LongJump
Modify the AA Dev wiki. (Changes will migrate at next dated release.) For a big new page or update to a PDF, add an entry to the "New in the Docs" list in the dev wiki Release Notes.	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 AA improvements as "cosmetic".

New Platform Feature

AgileApps

LongJump

Add to Dev wiki: http://agileappscloud.info/aadev For release notes: If ISV release is pending, add entry to New Platform Features section of ISV release notes. Otherwise, add entry to New Features section at top of standard Release Notes. If the Release Notes page is a redirect to Version NN.m Platform, convert the page: {[subst: ISV Release Notes}} Change the link that goes to the earlier-version release notes at the top of the page Generally, add a Learn More link. Otherwise, embed a link in the blurb. (In rare cases, there is nothing to link to.) Review the entry with SMEs For a new page: Add the appropriate category to the page: <noinclude> [[Category:User]] -- to be created [[Category:Design]] [[Category:Developer]] [[Category:Admin]] [[Category:Installer]] </noinclude> And add an entry to the appropriate index page: Users Index Designers Index Developers Index Sys Admin Index Installers Index

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/ljwiki Add entry to "New Features" section at top of Release Notes: http://lj.platformatyourservice.com/ljwiki/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.)

Cloud Release

(A dated release)

AgileApps

LongJump

Final cleanup / release prep: Monday: Circulate release notes to developers and Q/A. See if there are any additions. Wednesday: Copy release notes to aawiki. Send link to Janhavi. Friday: Add bug fixes to Release Notes iTrac: Issues > Manage Filters > My Filters > AgileApps - Recent Bug Fixes https://support.agileappscloud.com/networking/servicedesk/index.jsp#_reports Copy the contents of the table. Paste into a spreadsheet. Select the middle two columns. Paste into a text document. In the report, visit the cases. Correct the subject fields for accuracy. Add the table start:  ::{| border="1" cellpadding="5" cellspacing="1" Add table end: |} Add row starts: |- | Add column separators || Resolved: In the Release Note, add section header: ====Bug Fixes==== :iTrac Issues Paste in the bug fix table When done, modify the two dates in the filter to the date of the upcoming release (for use next month). Then save the filter: Change the dates. Click [Search] Save changes link appears in sidebar. Click it. New page appears: title=Save Current Filter. It shows the OLD filter. Click [Save] Find and fix all references to Template:TBD (As an alternative, leave them in place and remove them from the published wiki.) Verify that any references to Template:Beta are still appropriate. Remove the release date from the table of Upcoming Releases Release notes First release: Convert Release Notes page from redirect to date header. If a dated ISV release preceded this one, comment out the date header for that ISV release. (So cloud users see a single set of features for the latest date.) Change "New Features" at top of Release Notes to the date of the release. Create a another New Features section for any items that didn't make it in time. Push the messages file Launch VPN svn update Invoke script c:/www/scripts/upload_messages.bat Review the results. Press any key to close the window publishDevWiki (script) After Publishing In the archive dir, download the production backup made during the process. Delete one or more of the old ones. (Only 2 or 3 need to be kept. They consume space in the daily "disk-image" backup made by the system.) If an ISV-release date header was commented out in the Release Notes, uncomment it. Future cloud users will see two sections where there was one before. No matter. Next ISV release will have the dated section at the bottom of that release, and the top of the previous release. No matter. Post announcement to the AgileApps Yammer Group Template: #Cloud Release Blurb

Release notes First release: Convert Release Notes page from redirect to date header. If a dated ISV release preceded this one, comment out the date header for that ISV release. (So cloud users see a single set of features for the latest date.) Change "New Features" at top of Release Notes to the date of the release. Create a another New Features section for any items that didn't make it in time. There is nothing else to do for a LJ release. (By choice, the wiki always reflects the latest new features, even if they're not out yet.) After Publishing If an ISV-release date header was commented out in the Release Notes, uncomment it. Future cloud users will see two sections where there was one before. No matter. Next ISV release will have the dated section at the bottom of that release, and the top of the previous release. No matter.

New ISV Feature

(installable version feature or installation note)

AgileApps	LongJump
First change: Remove redirect in ISV Release Notes page {{subst: ISV Release Notes}} or copy most recent version Document the feature Add link to ISV Release Notes	First change: Remove redirect in 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

ISV Release

(version-numbered)

Release Prep

Circulate release notes to developers and Q/A. See if there are any additions. Send out help links with final slash to the release admin: http://agileappscloud.info/aa###/ http://isv.platformatyourservice.com/lj###/ (Context-sensitive help concatenates a page name to the help URL, so final slash is needed.) Add version number to header logo and favicon Path: www/custom_logos aa100.ico ==> aa###.ico Use eyedropper to select teal Trebuchet MS, normal, 10 aa100.png ==> aa###.png (watch directory -- defaults to last, not current) Edit using SnagIt editor Logo Text: Gil Sans MT font, bold, 48 pt. Teal color Version#: (TrueType) TT Arial, 12pt, greenish-gold color Font is not TT Arial Unicode MS. It's further down. Color is in the middle of second row of colors, right most of two adjacent w/similar color. lj100.ico ==> lj###.ico Use eyedropper to select blue Text: Trebuchet MS, normal, 12 lj100.png ==> lj###.png Version#: Gil Sans MT, 36 pt, custom blue (sample existing if not in palette) Add images to SVN and commit changes Push images to server

Release

AgileApps

LongJump

Final cleanup: Find and fix all references to Template:TBD Verify that any references to Template:Beta are still appropriate. In AA Dev wiki: Remove the release date from the table of Upcoming Releases Move "Release Notes" page to "Version ##.# Platform", leaving a redirect Change the link that goes to the earlier-version release notes at the top of the page Move 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.) Run the versionAgileAppsDevWiki script If needed, run the older x_versionAgileAppsProductionWiki to version the production wiki. The process is needed if the dev wiki happens to have things in that are not in the ISV release. But the reverse is more common: Things have been added to the development platform that will be in the ISV release, but which are not yet available in the cloud. After the versioning script completes: Copy items from New Platform Features in the ISV release notes to the New Features section at top of the (cloud) release notes page. Post announcement to the AgileApps Yammer Group. Template: #ISV Release Blurb Modify Readme for SAG Empower page: SVN:/techpubs/release_blurbs/AgileAppsReadme.html Adjust ##.# in heading Adjust 5 links to aa### When the new platform release is available, send to the current release maven (Sherwin, Sergey, or Sherwin) to include in the release notice sent to Steve O'Brien Review existing pages at http://empower.softwareag.com (Use the instructions in the accompanying README to go to the product listings.) Send global documentation link: Adjust the code below Send to Sabine Winterbauer for inclusion in http://documentation.softwareag.com Backup: Send to Dr. Marc Beckers--but only if the previous process fails Post-release follow-up Verify the Empower entry. NOTE: The Readme link goes to a download page. Clicking the "Download" link in that page then displays the Readme. That's the best that can be done with the Empower site software. There is no way to directly display the Readme when clicked. (The best that can be done is to prevent the user from having to download the README to read it.) Once the Empower entry is published and verified by self and Uday, use the ISV-release blurb template below to post a note to the Yammer group. Copy new features and bug fixes from installable release notes to the release notes for the next cloud release.

Move "Release Notes" page to "Version ## Platform", leaving a redirect Change the link that goes to the earlier-version release notes at the top of the page Move "ISV Release Notes" page to "Version ## Installable", leaving a redirect Run the versionLongJumpWiki script

 

Sample Announcements

Sample Release Blurbs for Yammer Group

Note: When I put in a link to current release notes, as here: http://agileappscloud.info/wiki/Release_Notes, then the paragraph Yammer would have found on 17 Jan is displayed. It's not showing the paragraph at the top of the most recent version of the page. The workaround is to leave "Release_Notes" off of the URL. That causes the first paragraph from the main page to appear. "Release_Notes" can then be added back, leaving at least a semi-meaningful blurb on the page.

Cloud Release Blurb

1. Date the blurb for the day after the wiki is published.
   (The wiki is published the day of the actual release, but the actual release may not happen until late in the evening--so we always tell customers that the release will be available the next day. The blurb should do the same.)
2. Post the blurb to the Yammer AgileApps Group

A new version of AgileApps Live will be in the cloud on Sat, xx YYY 2014.

Highlights include preference settings to determine how records are displayed, email signatures, editable subforms, external lookups, external data sources, and fault handling for web services, plus documentation enhancements.

Learn more: http://agileappscloud.info/wiki/Release_Notes

ISV Release Blurb

Post the blurb to the Yammer AgileApps Group

Version ##.# of the AgileApps Live installable is available at empower.softwareag.com

Highlights include ...

Learn more: http://agileappscloud.info/***ISV_WIKI***/ISV_Release_Notes

Note: Don't include the https:// to make a link that goes to the Empower site. Once you do, there does not seem to be any way to get Yammer to recognize the Release Notes link. (It looks like it will handle only one link at a time, and the https:// always dominates, whether it is added first, second, or together with the other.)

HTML code for documentation.softwareag.com

Under source control at techpubs/release_blurbs:

<h1>AgileApps Cloud</h1>
<tr>
    <td valign="top" nowrap="" colspan="3">
        <a href="http://agileappscloud.info/wiki">
            AgileApps Cloud (public)
        </a>
    </td>
</tr>
<tr>
    <td valign="top" nowrap="" colspan="3">
        <a href="http://agileappscloud.info/aa104/ISV_Release_Notes">
            AgileApps Cloud Installable Version 10.4 (private, on-premise cloud)
        </a>
    </td>
</tr>

Scripted Procedures

These procedures are accomplished by logging in to the Wiki platform and running a script.

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://agileappscloud.com/aadev/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 (aadev) to the production wiki aawiki

   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

Wiki Backups

• A MediaWiki site contains a number of wiki files and a database.
• The PHP files and wiki content files are in the {wikiName}/ directory.
• Each Wiki has its own database.
  The database contains page contents and edit history. Data is exported to a .sql file using mysqldump, and imported using mysql.
• This script makes a dated zip file that contains the .sql file and the aadev directory folder:

• ./scripts/backupDevWiki

• The archive of database backups maintained on the server is at /usr/share/mediawiki/archive.

To back up the development wiki:

1. Using PuTTY, log in to the Rackspace server
2. Run scripts/backupDevWiki to create the backup file (dev_backup_<date>.zip) in the archive/ directory.
3. Use FileZilla to download the backup to the local system

Note: A backup of the production (cloud) wiki is made automatically when the Dev wiki is published.

Wiki Versioning

When a major new release of the platform's Installable Version occurs, a point-in-time snapshot of the current wiki needs to be captured, for continued reference by an on-premise installation that won't have features that were added later, to the platform running in the cloud.

To make that work, the help link in the cloud instance points to .../wiki, while the help link in the installable points to .../{version}. Eg. .../aa90

To make that version:

1. Using PuTTY, log in to the Rackspace server
2. Run scripts/versionProductionWiki to create the new Wiki version
3. Follow the instructions at the end of the script to add a version number to the wiki header image and favicon.