Release Manager Notes

Before starting make sure your public keys are added to the KEYS file.

Task List for Royale Releases

Royale releases will consist of the bundling of all 3 repos (royale-compiler, royale-typedefs, royale-asjs) into a single source artifact, as well as convenience binaries of Maven artifacts, NPM artifacts and IDE-compatible artifacts.

The release manager must be able to run Maven and Ant and have an Adobe AIR SDK and Adobe Flash SDK (playerglobal.swc and Flash Player Projector Content Debugger) installed, and environment variables set up.

• AIR_HOME
• PLAYERGLOBAL_HOME
• FLASHPLAYER_DEBUGGER

Setup FLASHPLAYER_DEBUGGER on Windows is pretty straightforward, but Mac requires a bit more steps to discover what is path to Flash Player Projector Content Debugger.

1. Once you download Flash Player Projector Content Debugger unpack it from dmg file copy it in some trusted place
2. Right click on file and choose Show Package Contents
3. Choose from opened folder Contents -> MacOS
4. Copy path to file Flash Player Debugger and setup environment variable:

FLASHPLAYER_DEBUGGER='/yourpathtoFlash Player Projector Content Debugger/Contents/MacOS/Flash Player Debugger'

Maven release steps use the Maven release plugin which uses SSH instead of HTTPS to connect to Git. So you must first follow the steps for their OS even though you have 2FA set up for regular GitHub work:

• Windows
• Mac OSX

It appears that Maven will do its work without updating the local working copy. So doing a "git pull" after the Maven steps is advised. For example, Maven pushed changes and a new branch to the remote, but my local working copy still said I had changes to commit.

Canceling an RC

To cancel an RC and generate a new RC, you have to revert certain changes that Maven made to the release branch. I have not tried the Maven Release Plugin's rollback capability because the documentation implies it would only work before you use the "perform" step.

If the plan is to accept some changes to the release branch and create a new RC, run "git checkout " to switch to the release branch and do a "git pull --rebase" to sync it up. Then look at the log via "git log". You should see some log entries. One should say:

[maven-release-plugin] prepare for next development iteration

Another should be:

[maven-release-plugin] prepare release org.apache.royale.<repo>-<release version>-rc<RC#>

In the royale-asjs and royale-typedefs branches there may be a third:

update other poms to current version

and fourth:

remove SNAPSHOT from compiler-build-tools versions

Revert these entries via "git revert "

Do the above for all 3 repos. Then you can accept the changes to the release branch and run the "maven" step again. Note that you should not merge the develop branch into the release branch because Maven has already updated the develop branch to the next release version.

Next, go find the staging repository for Royale in the Apache Nexus. In the left navigator choose "Staging Repositories", find "orgapacheroyale" in the top right list, select the checkbox, and click on the "Drop" button. Wait a few seconds then refresh the page and it should be gone.

Fixing an RC

Some times, during the creation of an RC, you'll see something you want to change before you tell everyone to start examining the RC. In order to use the "maven" step again, you will have to undo things as described in "Canceling an RC", but also remove any tags in Git that the "maven" step created. Make sure the repos are synced up and then on each of the 3 repos do "git tag" to list the tags. Look for the tag for that RC. It will look like "org.apache.royale.compiler-0.9.0-rc2" (or 'typedefs' or 'framework' instead of 'compiler'). Delete the tag locally with "git tag -d " then delete the tag remotely with "git push origin :refs/tags/" (for example: "git push origin :refs/tags/org.apache.royale.compiler-0.9.0-rc2").

Checking Versions (Before you start)

Theoretically, you will never need to do this, but sometimes the version numbers used in the builds will get out of sync in the repos due to incorrect reverts or other changes going on in the develop branch. Here are the tests I use to check that the version numbers are correct. You will need to use grep, so on Windows, you'll probably need Cygwin or some other BASH shell.

The following uses the example of trying to release 0.9.4. Where an example also uses 0.9.3 or 0.9.5 it is essentially testing that version numbers aren't ahead or behind. In each repo, run:

git pull --rebase

This syncs up the repo.

git branch --all

This displays all of the branches. There should be branches of the form 'remotes/origin/release/0.9.0' for previous releases, but not for the current release. If there is, delete the branch for this version (assuming it doesn't have any important changes). To delete a branch, run "git push --delete origin release/0.9.x" and if you have a local copy of the branch, run "git branch -d release0.9.x"

git tag

This displays all of the tags. There should be tags of the form 'apache-royale-0.9.0' for previous releases, but not for the current release. If there is, delete the tag (maybe ask on dev@ if there is any reason why that tag exists, or check commits@ for when it got created.

royale-compiler

Run 'ant wipe-all' to remove all generated code. Then run:

grep -r '0\.9\.4' *

This should result in lots of files having '0.9.4-SNAPSHOT' and build.properties having just '0.9.4'. If entries were added to RELEASE_NOTES then 0.9.4 should be in RELEASE_NOTES as well.

grep -r '0\.9\.3' *

This should only show RELEASE_NOTES, if anything

grep -r '0\.9\.5' *

This should not return anything.

royale-typedefs

Run "ant wipe" to remove all generated code. Then run:

grep -r '0\.9\.4' *

This should result in lots of files having '0.9.4-SNAPSHOT' (and not just "0.9.4"). The top-level pom.xml should have:

<royale.compiler.version>0.9.4-SNAPSHOT</royale.compiler.version>

There shouldn't be any other files with that version in it.

grep -r '0\.9\.3' *

No files should mention the older version

grep -r '0\.9\.5' *

No files should mention the newer version.

royale-asjs

Run "ant super-clean" to remove all generated code. Then run:

grep -r '0\.9\.4' * | grep -v @productversion

The grep -v filters out any hits from ASDoc @productversion so it is easier to see the build-related versions. This should result in lots of files having '0.9.4-SNAPSHOT' (and not just "0.9.4"). The top-level pom.xml should have:

<royale.compiler.version>0.9.4-SNAPSHOT</royale.compiler.version>

and

<royale.typedefs.version>0.9.4-SNAPSHOT</royale.typedefs.version>

The following files will have just plain "0.9.4" in it:

• build.properties
• various -app.xml files in examples
• flex-sdk-description.xml
• npm/js-only/package.json
• npm/js-swf/package.json
• package.json
• a few .as files in ASDoc comments.
• the RELEASE_NOTES

grep -r '0\.9\.3' * | grep -v @productversion

This should not only return the RELEASE_NOTES and a few files with ASDOC, but also the main pom.xml where it says:

<tag>release/0.9.3</tag>

The tag should be for the older version as the Maven release process will update the version with the tag it makes for the release branch. Not sure what will happen if that is out of sync.

grep -r '0\.9\.5' *

No files should mention the newer version.

Other setup

Make sure you have a settings.xml in your .m2 folder that has credentials for deploying artifacts to repository.apache.org. Follow instructions here: https://maven.apache.org/settings.html. Make sure you have entries like:

<servers>
  <server>
    <id>apache.releases.https</id>
    <username>...</username>
    <password>...</password>
  </server>
  <server>
    <id>apache.snapshots.https</id>
    <username>...</username>
    <password>...</password>
  </server>
</servers>

A full settings.xml file with Apache credentials might look like this:

<?xml version="1.0" encoding="UTF-8"?>
<settings xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd" xmlns="http://maven.apache.org/SETTINGS/1.1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <servers>
    <!-- Apache Repo Settings -->
    <server>
        <id>apache.snapshots.https</id>
        <username>{user-id}</username>
        <password>{user-pass}</password>
    </server>
    <server>
        <id>apache.releases.https</id>
        <username>{user-id}</username>
        <password>{user-pass}</password>
    </server>
  </servers>
</settings>

SVN

Releases are staged and distributed on SVN at dist.apache.org. EVERY ASF release is there so don't sync the entire repo. Instead do partial checkouts of just the Royale folder in dev/Royale and release/Royale.

To get dist.apache.org, use:

svn co --depth empty https://dist.apache.org/repos/dist <destination-folder>

Then change to that folder and do:

svn update --depth empty dev
svn update --depth empty release

That should introduce dev and release folders under dist. Then change to the dev folder and do:

svn update royale

And do the same in the release folder.

Using Windows

Set environment variable:

JAVA_TOOL_OPTIONS=-Dfile.encoding=UTF-8

The "-" in UTF-8 is important. Sass will fail otherwise. Next, make sure you are set up to use SSH for GitHub by following this link. You may need to use Git-Bash to execute the the part about setting up a key-agent here.

Even though you can use GPG4Win to sign releases from the command prompt, Maven might try to use GitBash's gpg which has a different keystore, and signing will fail. If you run into this, export your keys with GPG4Win and import them in GitBash's GPG. Use GitBash to verify if your key is in the keystore via:

gpg --list-keys

and

gpg --list-secret-keys

For me, it was empty in GitBash but GPG4Win listed my keys. I found mykey ID (looks like an 8 digit hexadecimal number) and used that as described below. Per this link, I was able to use something like this in GPG4Win:

gpg --export ${ID} > public.key
gpg --export-secret-key ${ID} > private.key

And then import in GitBash via:

gpg --import < public.key
gpg --import < private.key

Then to build an RC, open a command prompt and run start-ssh-agent. Then you should be able to run the releasecandidate.xml scripts.

Using Powershell in Windows

There are articles on the internet about using Git and Powershell, but I found that I could just use Git from Powershell without all of that setup.

I first had to set the MAVEN_OPTS environment variable to make sure there is enough heap space:

MAVEN_OPTS='-Xmx2048m -XX:-UseGCOverheadLimit'

Then, I opened a Powershell window and ran:

"C:\Program Files\Git\cmd\start-ssh-agent.cmd"

For some reason, that causes the Powershell command to go away. I think start-ssh-agent runs a command prompt shell afterwards instead of Powershell, so that means that Powershell features go away.

Note (November 11, 2018): The above did not work for me. The internet says that OpenSSH is now shipped with Windows and Powershell knows how to work with it but Git doesn't use it by default. Also, OpenSSH seems to be disabled by default. I took the following steps:

In c:\Users<username>.gitconfig, add:

[core]
sshcommand = c:/Windows/System32/OpenSSH/ssh.exe

Then in the Window "Services" app, I found OpenSSH Authentication service was disabled. I right-clicked on the word "disabled" and changed "disabled" to Manual".

Then in Powershell, I ran:

Start-Service ssh-agent
ssh-add C:\Users\<username>\.ssh\id_rsa

This asked me for the passphrase for the key.

Then test ssh by making a small commit (I changed royale-compiler GIT-TEST.txt) and pushing using the SSH user:

git push [email protected]:apache/royale-compiler.git

Because Powershell limits to 9999 lines of console output and the build spits out many more lines than that, having Powershell fork output to a file is useful. So I would launch another Powershell window and run Ant in there, but pipe the output to a file via:

ant -f releasecandidate.xml <options> | Tee-Object -file <path to log>

local.properties

It is recommended to create releases in a separate folder than your Git working copies. Create an empty folder and create in it a local.properties file. In local.properties, set:

my.name=Alex Harui

svn.dist.dev=C:\\svn\\apache\\dist\\dev
svn.dist.release=C:\\svn\\apache\\dist\\release
svn=C:\\Program Files\\CollabNet\\Subversion Client\\svn.exe

Use double blackslash on Windows and single forward slash on Mac. Set the svn properties to the appropriate folders in dist.apache.org

Release Steps

Note: There is some evidence that internet connection bandwidth is really important. The scripts kept hanging for me trying to access the Maven repo if I was watching videos on another computer while waiting for the scripts to finish.

There are at least two ways of creating release artifacts: A) Using the CI Server (Instructions below) B) Using the releasecandidate.xml scripts

NOTE: The CI Server is "shared" so credentials should not be stored on that machine. The Git config credential.helper should not appear in git config --list. If it does, use git config --unset credential.helper to unset it. You may need to add --global or --system parameters as well.

Similarly, do not set the Git config user.name or user.email on the CI server. The CI jobs should ask for a user.name and set it on the command-line. If you need to do a manual commit Git will tell you to set the config properties, but don't do it. Use git -c user.name="My Name" -c user.email="[email protected]" commit instead.

The release scripts assume that each of the 3 repos is properly versioned. The scripts assume that the version numbers in certain files reflect the version being released. The RM may need to verify that the following files have the following versions: A) All pom.xml files have the SNAPSHOT version of the release. So if releasing 0.9.4, then the pom.xml files should be version 0.9.4-SNAPSHOT. There are some properties with versions in the pom.xml files that may need to be upgraded to 0.9.4 as well. B) build.properties lists the correct version (without -SNAPSHOT).

Also make sure that your SVN repos for dist/dev/Royale are updated without conflicts.

Assuming you have set up properly, creating a release candidate involves:

1. Run each Release Steps job on the CI Server in order. As each job completes, it will send an email to [email protected] explaining what to do next. The final steps should generate the packages and set up emails to send to the list for vote and discussion.

For details on each job see: Release Steps Jobs on Jenkins When the vote passes, do

1. Verify that your SVN is up to date. Do an "svn status" on dist/dev and dist/release. If you have non-Royale folders, they must be up to date otherwise the svn commit will fail.
2. Run: ant -f releasecandidate.xml "-Drelease.version=x.y.z" -Drc=n release Don't forget to run push --all in each repo folder
3. Hit the release button on Apache Nexus.

The released artifacts should end up on dist/release Don't delete the older release until the mirrors have caught up. If there is more than one older release in the royale folder, use "svn rm" to delete it.

You should also clean up the RC folders on dist/dev

4. Find the newly created tag on the GitHub repo tags list and create a GitHub release based on that.

5. Draft the announcement and send it to dev list.

6. Wait 48 hours and address any feedback given on the announcement draft.

7. Send the announcement to dev and user lists.

Troubleshooting

If you see this error:

gpg: signing failed: Inappropriate ioctl for device

Run first:

export GPG_TTY=$(tty)

---

Did you hope to test releasecandidate.xml locally, and discovered that it unexpectedly pushed some commits upstream?

This can be fixed by following the Canceling an RC steps above.

Edit releasecandidate.xml locally and uncomment lines with <!--<arg value="-DpushChanges=false" />--> to avoid pushing any commits that the script makes on your behalf.