Release Plan
This document contains all the steps needed for a new release of OpenShot Video Editor. Many things need to happen in a specific sequence during a release, and this is my attempt to document the process.
Before we can start the release process, we need to update the POT translation template (https://github.com/OpenShot/openshot-qt/blob/develop/src/language/OpenShot/OpenShot.pot), which contains all translatable strings contained in OpenShot. Run the following script to update the template file:
python3 src/language/generate_translations.py
Once the OpenShot.pot file is updated, merge this change into the develop branch. LaunchPad.net no longer automatically detects a change in this file, so we will need to manually upload the POT file. Translators can use LaunchPad to translate these English phrases and words into their own languages. If you are interested in helping translate OpenShot, instructions are available.
- 1.1 - Run the generate_translations.py script
- 1.2 - Merge OpenShot.pot into
developbranch - 1.3 - Manually upload OpenShot.pot to LaunchPad
- 1.4 - Manually approve OpenShot.pot upload (click "edit" icon)
- 1.5 - Verify new translatable strings appear on LaunchPad
- 1.6 - Notify the community (Facebook, Blog post, E-mail [email protected])
Allow the community at least 7 days (and more if possible) to answer the call and submit translations through LaunchPad. Each night, translations are automatically committed to a Bazaar code branch (https://bazaar.launchpad.net/~openshot.code/openshot/translations-2.0/). Run the following commands on that branch to generate the final translation files needed by OpenShot:
bzr branch lp:~openshot.code/openshot/translations-2.0
cd translations-2.0
python3 compile.py
This will create the following files:
- openshot_lang.qrc (a resource file with a list of supported languages)
- src/locale/OpenShot/output/OpenShot.[LANG-CODE].qm (one of these files for each language)
Now copy those files into the openshot-qt source code, into the /src/language/ folder. Next, run the following commands for the openshot-qt Git repo:
cd openshot-qt
cd src/language
make
pyrcc5 openshot_lang.qrc -o openshot_lang.py
That will modify the openshot_lang.py file with all the latest translations. Now merge those changes into the develop branch.
- 2.1 - Pull or branch translations-2.0 bzr branch
- 2.2 - Run compile.py script
- 2.3 - Copy openshot_lang.qrc and *.qm files to openshot-qt (/src/language/ folder)
- 2.4 - Run
pyrcc5 openshot_lang.qrc -o openshot_lang.pyfrom thesrc/languagefolder - 2.5 - Download donors and supporter credits into
/src/settings/supporters.json - 2.6 - Merge these changes into openshot-qt
developbranch
Now that the openshot-qt develop branch has updated translations, we need to verify there are no issues in the translations, such as missing placeholders (%s) or the wrong number of placeholders. Run the following script to test all translation files:
python3 src/language/test_translations.py
If any errors are reported, fix them in LaunchPad and run through the above Download Translations instructions again.
- 3.1 - Run test_translations.py script
- 3.2 - Fix any reported issues on LaunchPad
OpenShot includes a small scaled copy of each image used in the UI (transitions, effects, titles, blender animations), and before a release we need to update those so they correctly reflect our latest image and icon assets.
- 4.1 - Delete the old image cache files:
/src/images/cache/* - 4.2 - Delete the old user image cache files:
~/.openshot_qt/cache/ - 4.3 - Run
python3 images/generate_cache.py(this generates cache files at 2 resolutions for High DPI support) - 4.4 - Verify cache images are updated, and new ones are added to Git
- 4.5 - Launch OpenShot, click on all tabs (transitions, effects, emojis) and view (titles, animated titles), and verify no cache icons appear in
~/.openshot_qt/cache/
Now that we have verified all translations are updated and working correctly, we need to create a release branch for all 3 OpenShot Git repos (IN THIS ORDER: libopenshot-audio, libopenshot, and openshot-qt). Run the following commands for each Git repo folder (with the current date - YEAR-MONTH-DAY):
Bump version #s and remove -dev1 from all versions.
cd [openshot-qt GIT REPO FOLDER]
nano xdg/org.openshot.OpenShot.appdata.xml
cd [GIT REPO FOLDER]
git checkout develop
nano CMakeLists.txt (increment PROJECT_VERSION_FULL, and PROJECT_SO_VERSION for libopenshot-audio / libopenshot)
nano src/CMakeLists.txt (increment FIND_PACKAGE(OpenShotAudio 0.1.9 REQUIRED) for libopenshot)
nano src/classes/info.py (increment VERSION, MINIMUM_LIBOPENSHOT_VERSION, and DATE for openshot-qt)
git commit -m "Bumping version to ..."
cd [GIT REPO FOLDER]
git checkout develop
git pull
git checkout -b release-20190320 (Replace the Date)
git push [WAIT FOR EACH RELEASE BRANCH TO BUILD SUCCESSFULLY ON GITLAB, BEFORE PUSHING THE NEXT ONE: libopenshot-audio, libopenshot, and then openshot-qt]
This will create and push a release branch to GitHub for each of our OpenShot repos. Our build servers will detect these new branches, and build libraries, package dependencies, and create installers for Linux, Mac, and Windows. It is VERY IMPORTANT that these release branches be pushed in the correct order (libopenshot-audio, libopenshot, and openshot-qt). Each branch consumes the GitLab artifacts from the previous one. These installers will be uploaded automatically to GitHub with the naming pattern: OpenShot-v[VERSION]-release-candidate-[DATE], and will appear on https://www.openshot.org/download/ (under Daily Builds).
NOTE: If libopenshot-audio or libopenshot does not have any changes, you can push the previous release tag directly to a new branch:
git checkout -b release-20210904 v0.2.1
- 5.0 - Bump version #s (on all 3 repos)
- 5.1 - Create
release-DATEbranches (libopenshot-audio, libopenshot, and openshot-qt... IN THIS ORDER) - 5.2 - Verify version numbers updated
- 5.3 - Verify libopenshot-audio on GitLab and verify build succeeds
- 5.4 - Verify libopenshot on GitLab and verify build succeeds
- 5.5 - Verify openshot-qt on GitLab (and dependency version to libopenshot) and verify build succeeds
- 5.6 - Verify release-candidate installers appeared on website
- 5.7 - Create a WIP Release PR on GitHub for each repo (libopenshot-audio, libopenshot, and openshot-qt), pointing to master branch. This will allow the community to view the release, participate in merging changes into it, and can be used in the future to view the comments and collaboration for each release.
It's time for some serious testing! Share the links to our new release candidates with the community (primarily Zulip and Reddit), in hopes that a few people will help test them out. We have an easy-to-follow testing plan, with test media files available to make this testing process as consistent as possible. Successful tests should be verified on all 3 OSes before continuing. New release candidate commits will likely be needed for fixing bugs and continuing to update translations. Repeat these steps until all testing plans are successful on all OSes.
- 6.1 - Notify community (on Zulip) of release candidates
- 6.2 - Run testing plan successfully on all 3 OSes (Linux, Mac, and Windows)
- 6.3 - Fix any bugs in release branch (and repeat these steps again)
Now that we have verified and tested the release candidate, it is time to generate the release notes and GitHub tags & pre-releases. This step will create "version" tags for each repository, so it's important this step comes after testing. If more changes are committed after this step, you will need to delete the GitHub pre-releases and tags before deploying again (in order for our automatic changelog logic to include the correct commits inside the About OpenShot->Changelog dialog, and on our GitHub pre-release pages).
Press the Deployer button on the openshot-qt GitLab CI build of the release branch. This will do the following things:
- Parse and format all changelogs (from the current release candidate build)
- Create a "version" tag for each repository
- Create a "pre-release" for each repository (UNRElEASED)
- Automatically add the changelog in the body of each pre-release page
- Create a "pre-release" Blog post on openshot.org (UNPUBLISHED)
- Automatically add the changelog in the body of the blog post
Now comes a manual process, to filter through the changelogs, looking for the most significant changes, and adding them to the "Highlights & Features" bullets under each GitHub pre-release page. Reorder these highlights, based on perceived importance, most important at the top, to least important at the bottom.
# Manual command to create the changelog files (if you are not using GitLab CI)
cd [GIT REPO FOLDER]
git log $(git describe --tags --abbrev=0)..HEAD --oneline --pretty=format:"%C(auto,yellow)%h%C(auto,magenta)% %C(auto,blue)%>(12,trunc)%ad %C(auto,green)%<(25,trunc)%aN%C(auto,reset)%s%C(auto,red)% gD% D" --date=short > "[GIT REPO FOLDER].log"
- 7.1 - Click "Deployer" button on GitLab CI for the release branch
- 7.2 - Manually review changelogs and create "highlights" for each GitHub pre-release
- 7.3 - Update pre-release blog post with all "highlights" as well
Now that we have verified our release candidate has successfully passed our testing plan on all 3 OSes, it is time for the moment of truth! It is time to merge our release branch PRs into our master branch. Once this has been done, our build servers will detect that the master branches have been updated, and will prepare the final builds, dependencies, and installers. A new Release will also be created on GitHub, which will contain all the installers just created. Once completed, each installer should be downloaded and verified, to be sure nothing was interrupted during the upload. These installers do not automatically appear on https://www.openshot.org/download/ (this will happen at a later time).
- 8.1 - Verify PR target (master <= release) for each repo
- 8.2 - Merge them in order (libopenshot-audio, libopenshot, and openshot-qt), and wait for each to finish before starting the next.
- 8.3 - Verify all builds succeed (one by one)
- 8.4 - Verify all builds are uploaded to the correct GitHub release page
Tag the final commit in the master branch with the following pattern: v[VERSION]. Run the following commands for ONLY libopenshot and libopenshot-audio repos, or use GitHub to create these tags:
cd [GIT REPO FOLDER]
git fetch
git checkout master
git pull
git tag v[MAJOR-MINOR-PATCH]
git push origin --tags
- 9.1 - Tag
libopenshot-audioandlibopenshotGit repos with the version number (for example: v2.0.0) - 9.2 - Push tags to GitHub
- 9.3 - Verify all tags appear on GitHub
Historically, we have always uploaded source code archives on LaunchPad.net. Run the following commands to create the archive files for each repo folder.
cd [GIT REPO FOLDER]
git checkout master
git pull
git archive --format=tar.gz -o [GIT REPO]-[VERSION].tar.gz HEAD
gpg --armor --sign --detach-sig [GIT REPO]-[VERSION].tar.gz
- 10.1 - Create archives (and GPG signatures) of source code (tar.gz)
- 10.2 - Upload archive for openshot-qt to LaunchPad.net
- 10.3 - Upload archive for libopenshot to LaunchPad.net
We now need to merge our master branch back into our develop branch, so our develop branch can also contain all the final changes from our release. However, there will likely be a conflict between version numbers. The following steps are recommended, since merging 2 protected branches (develop, master) will not allow us to resolve any conflicts.
NOTE: Be sure to bump the -dev1 version before merging into develop
cd [GIT REPO FOLDER]
git checkout master
git pull
git checkout develop
git pull
git checkout -b merge-master-into-develop
git merge master (MANUALLY RESOLVE ANY CONFLICTS)
# UPDATE '-dev2' version
git push
- 11.1 - Create PR for each repo (use a new, unprotected branch to merge master first)
- 11.2 - Merge them in order (libopenshot-audio, libopenshot, and openshot-qt)
- 11.3 - Verify all builds succeed
Our daily and stable PPA (used for distributing OpenShot for Debian-based Linux distros) needs to be updated for each new release. Our daily LaunchPad recipe only uses source code from the develop branch, so be sure to merge master back into develop before this step. Run the following commands to update the Debian packaging.
git clone git+ssh://[email protected]/openshot-packaging
cd openshot-packaging
# Libopenshot-audio Packaging
cd libopenshot-audio/debian
dch -i # COPY / PASTE the new revision at the top of the Debian changelog file
nano control # Update SO AND Replaces sections
git mv libopenshot-audio[OLD-SO].install libopenshot-audio[NEW-SO].install
grep "libopenshot-audio[OLD-SO]" * # Look for any old references
git add changelog control
git status # Verify all files are staged for commit
git commit -m 'New upstream release of libopenshot-audio for [VERSION]'
git push launchpad
# Libopenshot Packaging
cd libopenshot/debian
dch -i # COPY / PASTE the new revision at the top of the Debian changelog file
nano control # Update SO AND Replaces sections
git mv libopenshot[OLD-SO].install libopenshot[NEW-SO].install
grep "libopenshot[OLD-SO]" * # Look for any old references
git add changelog control
git status # Verify all files are staged for commit
git commit -m 'New upstream release of libopenshot for [VERSION]'
git push launchpad
# Openshot-qt Packaging
cd openshot-qt/debian
dch -i # COPY / PASTE the new revision at the top of the Debian changelog file
nano control # Check if any changes are needed
git add changelog control
git status # Verify all files are staged for commit
git commit -m 'New upstream release of openshot-qt for [VERSION]'
git push launchpad
- 12.1 - Update libopenshot-audio debian packaging and verify build succeeds
- 12.2 - Update libopenshot debian packaging and verify build succeeds
- 12.3 - Update openshot-qt debian packaging and verify build succeeds
- 12.4 - Verify packages appear in daily PPA
Now that we have verified the daily PPA has updated (and correctly versioned) packages, we need to copy them to our stable PPA. Choose Stable PPA in the first drop-down, Same Series in the second drop-down, and Copy Package in the final selection. Then click the Copy Packages button.
- 13.1 - Copy packages from daily PPA to stable PPA
It's time to put on the "marketing" hat and adapt our changelogs into a beautiful, readable, and enjoyable promotion of the latest OpenShot features, bug fixes, and improvements. This is also a great opportunity to encourage community engagement with our project, meet new volunteers, find new translators, and generate donations to help fund OpenShot infrastructure costs.
- 14.1 - Create demo video (optional but highly desirable)
- 14.2 - New blog post (with screenshots if needed)
- 14.3 - Do not publish the blog post yet (this happens at a later point)
Login to the openshot.org admin page (URL not displayed here), and create a new Release record. Enter the new version number, the current date, and the URL to the announcement blog post. This will update the current version on our website, will make out download page link to the new installers, and will notify all running clients a new update is available (on launch of OpenShot). After this is done, we have officially released OpenShot!
- 15.1 - Create new release record on openshot.org
- 15.2 - Verify the version number has updated correctly
- 15.3 - Verify the download page has updated correctly (including release notes link)
Now let's publish our blog post and let the world know about our latest release! Be creative and have fun with these posts. And listen carefully to any immediate feedback, in case users are having difficulty downloading or installing OpenShot.
- 16.1 - New Patreon post (linking to download page)
- 16.2 - Publish blog post
- 16.3 - Post Facebook, Twitter, Linux subreddit, and social media accounts (link to blog post)
- 16.4 - Respond to comments and observe if users are able to successfully run the new release