How to release

Content

Releasing
Re-create Molybdenum Reference (API Docs) in Confluence

Releasing

There are three types of projects regarding releasing:

XPI releases like the Molybdenum ITE or RunSeleniumRC
Regular Maven projects like automation
Master POMs or base POMs not belonging to a multi project setup

General information

The Molybdenum Project is using the maven release plugin for releasing the software.

Together with Subversion, there is a bug breaking the release plugin functionality. Follow the instructions below to deal with it.

mvn release:prepare will end up with an error that a file is already existing in the repository.

[INFO] ------------------------------------------------------------------------
[ERROR] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Unable to tag SCM
Provider message:
The svn tag command failed.
Command output:
svn: Commit failed (details follow):
svn: File '/svnroot/molybdenum/tags/VERSION_interpreter_0_0_1b1/src/main/java/org/molyb/interpreter/DefaultSeleneseCommandAdapter.java' already exists

To workaround this bug, you have to make an svn up and start again mvn release:prepare with -Dresume=true

Overall preparation

To allow write operations on molyb.org, an ssh key is needed. All the auth information is configured in the Maven settings.xml in the server section. This information is used for deployments to the ff-update areas as for the maven repo deployment as well.

<settings>
  <servers>
    <server>
      <id>molyb-repository</id>
      <username>username-on-molyb.org</username>
      <passphrase>key-passphrase or empty string</passphrase>
      <privateKey>path-to-private-key-file</privateKey>
    </server>
  </servers>
   .
   .
   .
</settings>

XPI releases

For XPIs in the Molybdenum Project, three maturity levels are defined

preview
beta
release

Molybdenum version string has the following format:
For preview and beta releases this should be the following: <version number>-<prev|b|rc><release number>.
For releases it is the plain version number.
A version number for XPIs consists of 3 one digit numbers separated by dots.

Steps todo for a release

check if you have installed the latest versions of Firefox 2.0, 3.0 and 3.5 and this versions are referenced in your settings.xml
Choose the right maturity level for your release in the POM of the project
Check if all JIRA Issues belonging to the planned release are fixed
Check if all main features are documented in the Wiki
goto to the root dir of the project to be released and type the following command:
```
mvn release:prepare -Dusername=<your svn username> -Dpassword=<your svn password>
```
You will be asked by maven for several information about the release.
1. The tag you'll be asked for is: VERSION<modulename><version number with dots replaced by underscores>
Possible you have to apply the workaround mentioned above

Do it!

mvn release:perform -Dusername=<your svn username> -Dpassword=<your svn password>

Now, the stuff is deployed on the molyb.org maven repo and the update areas
Deploy to sf.net. This has to be done manually.
Use the file with the highest maturity in the name from the target directory renamed to an extension .xpi. For downloaders updates will go to molyb.org update areas.
Deploy to AMO. Even that has to be done manually.
1. For all preview and beta maturity level releases, leave a note for the reviewer: This is an experimental release.
2. Put a link to the deployed test results on molyb.org/maven-sites as comment to the reviewer.
3. Put a link to our Feature page in the release notes.
  Use the file without any maturity in the name renamed to an extension .xpi. Updates are organized by AMO.
spread the news using twitter.

Re-create Molybdenum Reference (API Docs) in Confluence

molybdenum-xpi$> mvn clean generate-resources -P confluence

Now check that molybdenum-dist/target/api-docs/confluence contains the following folders:

 |_ moly
 |_ moly-readonly
 |_ selenium-core
 |_ selenium-core-readonly
 |_ reference.txt\\

The -readonly directories do contain the content maintained in confluence.
The directories "moly" and "selenium-core" do contain the content generated from JsDocs. Those are the directories you want to import in confluence, thus overriding previous API Docs with new content. You'll need the reference.txt as well as it contains the overview page.

Login to molyb.org via SSH and go to /tmp folder
```
mkdir import-`date +%F`
```
Copy all content from molybdenum-dist/target/api-docs/confluence into that folder
Make it accessible for tomcat user running confluence:
```
sudo chown -R tomcat:tomcat /tmp/import-`date +%F`/
```
Compare reference index with previous version (see an example):
```
diff -by --suppress-common-lines \
  /home/kilian/temp-imports/import-2008-08-10/reference.txt \
  /tmp/import-`date +%F`/reference.txt \
  > /tmp/import-`date +%F`_reference_index_diff.txt
```
and make sure which commands have been added and removed.
If Selenium commands are affected, remember them to document em in wiki later on (in the associated readonly file)

Now examine the new or changed molybdenum commands (see example):

Get a list of changed files
TODO: improve this script

for i in ` diff -by --width=300 --suppress-common-lines \
  /home/kilian/temp-imports/old-stuff/reference.txt \
  /tmp/import-2008-12-05/reference.txt \
  | grep -v selcore \
  | awk ' BEGIN {FS="|"; RS="]"} { print $2 }'`; \
  do find /tmp/import-2008-12-05/ -name $i-apidoc.txt \
  >> /tmp/import-2008-12-05_affected_moly_files.txt; \
  done;

Make sure @since annotation is present

for i in `cat /tmp/import-2008-12-05_affected_moly_files.txt` ;\
 do grep --files-without-match  "since 0.7.1" $i;\
 done;

Log in to confluence as Space Admin

Goto Dashboard -> Sandbox -> Browse Space -> Space Admin -> Import Pages from Disk
Choose folder "/tmp/import-<date>/moly" and select checkboxes "Trim file extensions" as well as "Overwrite existing pages" (1)
Repeat with folder "/tmp/import-<date>/selenium-core"
If new commands have been added to Molybdenum:
Choose folder "/tmp/import-<date>/moly-readonly" and select checkboxes "Trim file extensions" but DO NOT use "Overwrite existing pages"
If new commands have been added to Selenium:
Choose folder "/tmp/import-<date>/selenium-core-readonly" and select checkboxes "Trim file extensions" but DO NOT use "Overwrite existing pages"
Now for the index file reference.txt simple use the base folder "/tmp/import-<date>/" ignoring any warnings for the already imported sub dirs. TODO: this can be improved.
Check that content has been imported correctly in Sandbox by examining page "reference". Note that the "xyz-apidoc" pages are including their counterpart with space key "MOLYB:". You need to change one of those includes to "SAND:" for testing.
Now you're ready to repeat the last steps in the Molybdenum Space
Now copy the contents of imported "reference" page into the page "Molybdenum Command Reference"

(1) if you don't check "Override existing pages", during import, pages being overwritten will have been renamed: e.g. "loadVars-action-moly-apidoc" to "loadVars-action-moly-apidoc2" etc. From time to time, delete these old, orphaned pages

Deleting orphaned pages

I have not found any mechanism or plugin to bulk delete orphaned pages in confluence. So I came up with these simple moly scripts delete each orphaned site page by page:

deleteOrphanedPagesInSandbox.xml	download	run
deleteOrphanedPages.xml	download	run

However, be aware of those issues, making the solution impractical for us:
Issue: Included pages appear as orphaned pages
Issue: Orphaned Pages Query is slow

Here's a workaround for deleting at least the pages containing "selcore1" or "apidoc1". Run it in a loop and adjust it to your needs:

deleteOrphanedPagesWorkaround.xml

download

Run

Moving page to a different parent

Bulk moving several pages matching a specific pattern to a new parent page is not possible in confluence too as of today. But you may use this little script in a loop in order to move all pages at the root containing the name "selcore" below the page "Molybdenum Command Reference". Adjust the script to your needs:

dragAndDrop-to-command-reference.xml

download

run