summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJakob Heher <jakob.heher@iaik.tugraz.at>2022-07-08 15:11:39 +0200
committerJakob Heher <jakob.heher@iaik.tugraz.at>2022-07-08 15:11:39 +0200
commit8f8a5062990f630fe76ff8dde50271bf4999b769 (patch)
tree1c74d70a747ad4c0aebcc76fc316a073cd38a370
parent4d0eef628cedbcac69f41fd92cdbeb4c25189a34 (diff)
downloadpdf-over-8f8a5062990f630fe76ff8dde50271bf4999b769.tar.gz
pdf-over-8f8a5062990f630fe76ff8dde50271bf4999b769.tar.bz2
pdf-over-8f8a5062990f630fe76ff8dde50271bf4999b769.zip
add release readme to repo
-rw-r--r--release-Readme.md162
1 files changed, 162 insertions, 0 deletions
diff --git a/release-Readme.md b/release-Readme.md
new file mode 100644
index 00000000..d1c7ee53
--- /dev/null
+++ b/release-Readme.md
@@ -0,0 +1,162 @@
+==== RELEASE PREPARATION (versioning)
+(this creates a release tag which has versioning fields set appropriately, tags it, and pushes it to gitlab)
+ -> switch to your pdf-over clone
+ -> run mvn install to verify that it builds
+ -> you can skip this step if you are feeling brave
+ -> to actually prep a release, run mvn release:prepare -Dresume=false
+ -> this will prompt in the following order:
+ -> current release version (x.y.z)
+ -> current release tag (we typically use pdf-over-x.y.z)
+ -> new snapshot version (new version with -SNAPSHOT suffix)
+ -> it will then update version to release version, commit this & tag it with your release tag, update version to new snapshot version, and also commit this
+ -> to build an installer, make sure you manually check out the release tag afterwards, before you proceed!
+
+==== INSTALLER CREATION (you can do this at any time if you want to test a finalized bundle, you don't need to do it on a release tag, it's independent from the previous section)
+DO THIS ON LINUX! there are some weird quirks on other platforms, cf. issue #62 (if you are on windows, setup WSL, it works perfectly fine there)
+ -> ./publish.sh -Dks-pass={keystore password} -Dks-file={path to jks keystore file}
+ -> if you only want specific binaries, use ./publish.sh --profiles {windows|linux|mac} {remaining cli arguments as above}
+ -> this produces pdf-over-build/pdf-over_{windows|linux|mac}-{x86_64|aarch64}.{zip|jar|tar.gz} files
+ -> each platform setup has to be post-processed specifically, see respective section(s) below
+
+==== LINUX-SPECIFIC RELEASE PROCESS
+ nothing to do here, just rename pdf-over_linux-x86_64.jar to PDF-Over-{version}.jar and call it a day
+
+==== WINDOWS-SPECIFIC RELEASE PROCESS
+
+step 1: unpack zip archive
+ -> unpack to a temp directory, e.g. C:/temp/pdfover-packaging
+ -> check that it runs
+ -> try if pdf-over.exe works
+
+step 2: create signed installer
+ -> open pdf-over/installer/windows/PDF-Over.aip in Advanced Installer
+ -> update Product Details
+ -> Product version
+ -> attempt to switch away from page
+ -> when prompted, choose "Major Upgrade"
+ -> make sure the project is still valid (these *should* be correct, but...)
+ -> ensure that current files are included (Files and Folders)
+ -> include exactly the contents of the release zip
+ -> create shortcuts in "Start Menu -> Programs", "Desktop", and "Send To"
+ -> ensure Digital Signature configuration is correct
+ -> Use the A-SIT code signing cert from your cert store
+ -> We currently use http://timestamp.digicert.com for timestamping
+ -> SHA256 digest (or other appropriate choice)
+ -> ensure that Launch Conditions excludes 32-bit systems
+ -> ensure that the correct registry keys are setup (they already should be)
+ -> HKEY_CLASSES_ROOT.pdf\OpenWithProgids, REG_SZ `PDF-Over.pdf` `(empty value)`
+ -> HKEY_CLASSES_ROOT\Applications\PDF-Over.exe, REG_SZ `FriendlyAppName` `PDF-Over`
+ -> HKEY_CLASSES_ROOT\Applications\PDF-Over.exe\DefaultIcon, REG_SZ `(empty key)` `"[reference to PDFOver.exe]",0`
+ -> HKEY_CLASSES_ROOT\Applications\PDF-Over.exe\shell\open\command, REG_SZ `(empty key)` `"[reference to PDFOver.exe]" "%1"`
+ -> HKEY_CLASSES_ROOT\Applications\PDF-Over.exe\SupportedTypes, REG_SZ `.pdf` `(empty value)`
+ -> HKEY_CLASSES_ROOT\PDF-Over.pdf, REG_SZ `(empty key)` `PDF-Over`
+ -> HKEY_CLASSES_ROOT\PDF-Over.pdf\DefaultIcon, REG_SZ `(empty key)` `"[reference to PDFOver.exe]",0`
+ -> HKEY_CLASSES_ROOT\PDF-Over.pdf\shell\open\command `(empty key)` `"[reference to PDFOver.exe]" "%1"`
+ -> Click "Build" in the toolbar, this produces pdf-over/installer/windows/PDF-Over-SetupFiles/PDF-Over.msi
+ -> rename this to PDF-Over-{version}.msi; you are done
+
+==== MAC-SPECIFIC RELEASE PROCESS
+== (must be done on a Mac VM)
+
+step 0: make new working directory
+ mkdir /tmp/pdfover-packaging
+
+step 1: unpack archive bundle
+ unzip pdf-over_mac-x86_64.zip -d /tmp/pdfover-packaging
+ -> unzip to /tmp/pdfover-packaging
+ -> if you want to open this folder, use cmd+shift+g (the "go to" dialog)
+ -> set necessary files to be executable
+ -> cd /tmp/pdfover-packaging/
+ -> chmod +x *.sh jre/bin/*
+ -> check that it runs
+ -> ./pdf-over_mac.sh
+ -> (if you need to give permissions to java, navigate there in finder, then right click open to reveal the "OK" button)
+
+step 2: use platypus to create a bundle app
+ -> open platypus
+ -> set Script Path "/tmp/pdfover-packaging/pdf-over_mac.sh"
+ -> set App Name "PDF-Over"
+ -> set Interface "None"
+ -> for debugging, it can be useful to set this to "Text Window", and enable "Remain running after execution"
+ -> set Icon
+ -> Select .icns File
+ -> /tmp/pdfover-packaging/icons/icon.icns
+ -> set Identifier "at.a-sit.PDF-Over"
+ -> set Author "A-SIT"
+ -> set Version to current version
+ -> check "Accepts dropped items", click Settings, check "Accept dropped files"
+ -> add "jre", "lib" and "icons" (from /tmp/pdfover-packaging) to "Bundled Files"
+ -> click "Create App", this creates a new .app
+ -> save it in a new subfolder, as /tmp/pdfover-packaging/platypus/PDF-Over.app
+ -> check that it runs
+ -> (double-click the app in Finder)
+
+step 3: sign the platypus bundle
+ -> run ./signscript.sh platypus
+ -> it needs a .app in a folder, that's why we made a subfolder :) no, don't ask me why, and feel free to invest time into fixing it
+ -> this creates a signed app as /tmp/pdfover-packaging/pdf-over-{timestamp}/PDF-Over/PDF-Over.app
+
+step 4: prepare disk image
+ -> open disk utility
+ -> click file (at the top of your screen!), new image, blank image
+ -> name "PDF-Over", image format "Sparse Bundle Disk Package", size 250MB
+ -> save as /tmp/pdfover-packaging/pdf-over.sparsebundle
+ -> this has automatically mounted the bundle as a disk (in finder sidebar)
+ -> drag the following into this bundle:
+ -> the signed PDF-Over bundle from step 3
+ -> a shortcut to the Applications folder
+ -> background.png
+ -> move background.png to an invisible folder
+ -> Terminal: cd /Volumes/PDF-Over && mkdir .background && mv background.png .background
+ -> switch to the "PDF-Over" volume in Finder
+ -> switch Finder to icon view (if it isn't yet - it's the button to the right of the current folder name)
+ -> in Finder, click "View" (at the top), "Show View Options", enable "Always open in icon view" and "Browse in icon view"
+ -> set Background to "Picture", click to select, cmd+shift+g into /Volumes/PDF-Over/.background, and select background.png
+ -> adjust icon size & grid spacing until it looks centered
+
+step 5: bundle & notarize disk image
+ -> unmount the "PDF-Over" volume if it is still mounted
+ -> in Disk Utility, go to (at the top) Images, Convert
+ -> select /tmp/pdfover-packaging/pdf-over.sparsebundle from step 4 as input
+ -> set Image Format to "Compressed"
+ -> save as /tmp/pdfover-packaging/PDF-Over-{version}.dmg
+ -> mount it, verify that it looks good, then unmount it
+ -> submit the bundle to app for notarization
+ -> the first time, you will need to set your username & password
+ -> run ./notarizeAppCommand.sh PDF-Over-{version}.dmg
+ -> wait until notarization succeeds (usually <15min)
+ -> you can check with ./notarizeCheckSingleCommand.sh {uuid}
+ -> bundle the notarization ticket with the .dmg
+ -> xcrun stapler staple PDF-Over-{version}.dmg
+ -> you are done, this is the official mac release bundle!
+
+==== PUBLISHING INSTALLERS TO https://technology.a-sit.at/en/pdf-over/
+ -> log in to https://technology.a-sit.at/wp-admin/
+ -> LDAP login without @, if it doesn't work, talk to admins
+ -> click on "Downloads" in the sidebar
+ -> if you can't see it, you are missing permissions, talk to admins (again)
+ -> for each of the three PDF-Over downloads, click the title to edit, then...
+ -> scroll down, click "add download"
+ -> set correct version
+ -> click upload file
+ -> upload the respective installer file
+
+==== PUBLISHING INSTALLERS TO JOINUP
+ -> log into https://joinup.ec.europa.eu/
+ -> go to the pdf-over project page
+ -> "+", add release
+ -> set Name to "PDF-Over"
+ -> set Release number to {version}
+ -> add Release notes (orient yourself on previous versions')
+ -> leave rest unchanged
+ -> save as draft
+ -> use "+", add distribution to add setup files
+ -> publish the release
+ -> "..." in the far top right (inside the pdf-over banner)
+ -> edit
+ -> publish
+
+==== NOTIFYING CLIENTS OF THE UPDATE
+ -> sftp into https://updates.a-sit.at/
+ -> talk to admins about login (asitupdates@websites.iaik.tugraz.at)
+ -> update /html/pdf-over/Release.txt to the new version number