Skip to content

Release Plan

Jump to bottom
Jonathan Thomas edited this page Nov 17, 2022 · 58 revisions

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. Be sure to complete the Release Testing Plan first.

1. Call for Translations

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 develop branch
  • 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])

2. Download Translations & Credits

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.py from the src/language folder
  • 2.5 - Download donors and supporter credits into /src/settings/supporters.json
  • 2.6 - Merge these changes into openshot-qt develop branch

3. Test Translations

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

4. Update Icon/Image Cache

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

5. Create Release Branches

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-DATE branches (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.

6. Call for Testing

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)

7. Create Changelog

NOTE: Press the Deploy button on the openshot-qt GitLab CI build of the release branch

This is currently a manual process, to copy all Git logs, and create a hand-cleaned version (for each repo), without all the noise of merging, similar commits, mistake commits, etc.... I also reorder the log in order of importance (at least based on my perception). These change logs are used in a few places (such as the GitHub release page and LaunchPad release page), and it's nice to have them done before moving forward with the release. Run the following commands to output the git log for each repo or download them from the release candidate artifacts on GitLab (build/install-x64/share/*.log):

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 - Run script to generate change log files for each repo
  • 7.2 - Manually remove noise and duplicate entries
  • 7.3 - Re-order based on perceived importance
  • 7.4 - Save these files and place them in a safe place (we'll need them soon)

8. Merge Pull Requests (to master)

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

9. Tag Release

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-audio and libopenshot Git repos with the version number (for example: v2.0.0)
  • 9.2 - Push tags to GitHub
  • 9.3 - Verify all tags appear on GitHub

10. Create Archives (tar.gz) for LaunchPad

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

11. Create Pull Request (back to develop)

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

12. Debian Packaging (for Daily PPA)

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          # Add a 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
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          # Add a 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
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          # Add a 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

13. Update Stable 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.

14. Write Blog Post

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)

15. Website Release

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!

17. Publish Announcement

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

Want to help improve OpenShot (and make some friends in the process 🤗)? Please consider joining our open-source team by filling out this quick contributor form and introduce yourself! All volunteers are welcome, regardless of skills or skill level. Let's build something amazing!

Home

1. Community

2. Product

3. Troubleshooting

Clone this wiki locally