<p>This page contains detailed instructions for normal releases. Refer to <ahref="../06_releasing">Releasing a New NewPipe Version</a> for other information about releases.</p>
<li>Have at least maintainer rights on the NewPipe and NewPipeExtractor repos</li>
</ul>
<h3id="repositories">Repositories</h3>
<ul>
<li>Have a cloned NewPipe local repository (for the rest of the page, <code>origin</code> is assumed to be the remote at <code>github.com/TeamNewPipe/NewPipe</code>)</li>
<li>Add the <code>weblate</code> remote to the same local repository (the URL used below can be found on the Maintenance page on Weblate)<ul>
<li><code>git clean -fdx</code> to <strong>discard</strong> them all (<strong>CAUTION</strong>)</li>
</ul>
</li>
<li>Switch to the <code>dev</code> branch and make sure it is up-to-date with the remote:<ul>
<li><code>git checkout dev</code></li>
<li><code>git pull origin dev</code></li>
</ul>
</li>
</ul>
<h3id="version-name-and-conventions">Version name and conventions</h3>
<ul>
<li>Find the version code of the next release by looking for <code>versionCode</code> in <ahref="https://github.com/TeamNewPipe/NewPipe/blob/dev/app/build.gradle"><code>app/build.gradle</code></a>: You will add 1 to that value (from now on called <code>NEW_VERSION_CODE</code>) to get the new value (but do not edit the file yet)</li>
<li>Choose the version number of the next release according to <ahref="https://semver.org/">semantic versioning</a> (from now on called <code>X.X.X</code>)</li>
</ul>
<h3id="identification">Identification</h3>
<ul>
<li>Have <code>gpg</code> installed and usable on your PC</li>
<li>Have a GPG key, which can be used to verify that a file is really from you</li>
</ul>
<h2id="pull-changes-from-weblate">Pull changes from Weblate</h2>
<ul>
<li>Go to <ahref="https://hosted.weblate.org/projects/newpipe/#repository">Weblate's Maintenance tab</a></li>
<li>Press the <em>Lock</em> button to prevent translators from translating while you are creating commits; remember to <em>Unlock</em> later!</li>
<li>Press the <em>Update</em> button to update Weblate with the latest changes on NewPipe's <code>dev</code> branch</li>
<li>Press the <em>Commit</em> button, if needed, to make sure Weblate creates a commit for translations which have not been committed yet</li>
<li>Now go back to the local git repository</li>
<li>In case you followed these steps before, delete the <code>weblate-dev</code> branch<ul>
<li><code>git branch -D weblate-dev</code></li>
</ul>
</li>
<li>Fetch new changes from the <code>weblate</code> remote<ul>
<li><code>git fetch weblate</code></li>
</ul>
</li>
<li>Create a new branch starting from <code>weblate/dev</code>, named <code>weblate-dev</code>, and switch to it<ul>
<li>If you run <code>git log --oneline --graph</code> you should see a Weblate commit on top, and then all of the commits currently on the <code>dev</code> branch:</li>
<li>Switch back to the <code>dev</code> branch<ul>
<li><code>git checkout dev</code></li>
</ul>
</li>
<li>Merge <code>weblate-dev</code> into <code>dev</code>:<ul>
<li><code>git merge weblate-dev</code></li>
</ul>
</li>
</ul>
<h2id="create-a-changelog">Create a changelog</h2>
<ul>
<li>Finalize the draft changelog <ahref="https://github.com/TeamNewPipe/NewPipe/releases">kept on GitHub</a>, in case there are still some things to fill in<ul>
<li>Remove the temporary instructions, and the numbers before <code>-</code> which keep track of the order in which the PRs were merged, as that info is useful only for the blog post writers</li>
<li>Before removing that information, you may want to send the original changelog to the blogpost writers</li>
</ul>
</li>
<li>Create a new English changelog in the <ahref="https://github.com/TeamNewPipe/NewPipe/blob/dev/fastlane/metadata/android/en-US/changelogs/"><code>fastlane/metadata/android/en-US/changelogs/</code></a> folder</li>
<li>The file should be named <code>NEW_VERSION_CODE.txt</code>, using the new version code found in the <ahref="#preliminary-steps">Preliminary steps</a></li>
<li>Make sure you use the <code>•</code> for points (it looks nicer than <code>-</code>)</li>
<li>Capitalize the first letter in each point</li>
<li>Use English verbs as if you were asking someone to do something, so for example use "Fix abc" and not "Fixed abc"; this allows saving a few characters and using a consistent style</li>
<li>Prepend <code>[SERVICE]</code> to service-only changes (e.g. "• [YouTube] Add mixes")</li>
<li>Summarize only the most important changes from the draft release <ahref="https://github.com/TeamNewPipe/NewPipe/releases">kept on GitHub</a> (it contains all merged pull requests)</li>
<li>Make sure the file size is <strong>at most 500 bytes</strong>, in order to <strong>fit <ahref="https://f-droid.org/en/docs/All_About_Descriptions_Graphics_and_Screenshots/#fastlane-structure">F-Droid's changelog size limit</a> (!)</strong><ul>
<li>Tip: removing the newline at the end of the file saves 1 byte ;-)</li>
<p>Now there should be two new commits (the Weblate and changelog ones) on your local <code>dev</code> branch, which are not on NewPipe's remote <code>dev</code> branch.</p>
<ul>
<li>If you are an admin of the NewPipe repo, just push the changes to the remote <code>dev</code><ul>
<li><code>git push origin dev</code></li>
<li>If you are not an admin, create a pull request normally and ask someone with maintainer access to merge it</li>
</ul>
</li>
<li>Go to <ahref="https://hosted.weblate.org/projects/newpipe/#repository">Weblate's Maintenance tab</a></li>
<li>Press the <em>Update</em> button to update Weblate with the commit you just pushed on NewPipe's <code>dev</code> branch</li>
<li><strong>Press the <em>Unlock</em></strong> button to allow translators to translate the changelog and possibly other components (<strong>do not forget this step!</strong>)</li>
<li>Note that we had to do this process on NewPipe's <code>dev</code> branch because:<ul>
<li>Weblate's components are connected to NewPipe's <code>dev</code> branch, and will update changes from there</li>
<li>Weblate's git repo is not writable, so there is no way to push commits there manually</li>
<li>Edit the <ahref="https://github.com/TeamNewPipe/NewPipe/blob/dev/app/build.gradle"><code>app/build.gradle</code></a> file to update the extractor<ul>
<li>Set the NewPipeExtractor dependency version to a suitable one (usually <ahref="https://github.com/TeamNewPipe/NewPipeExtractor/commits/dev">the last commit in the NewPipeExtractor repo</a>)</li>
</ul>
</li>
<li>Commit the extractor update (if you used a specific version, append <code>to VERSION</code> to the commit message)<ul>
<li>Edit the <ahref="https://github.com/TeamNewPipe/NewPipe/blob/dev/app/build.gradle"><code>app/build.gradle</code></a> file to bump the release<ul>
<li>Set <code>versionCode</code> to <code>NEW_VERSION_CODE</code>, i.e. increment the value by 1 as described in the <ahref="#preliminary-steps">Preliminary steps</a></li>
<li>Set <code>versionName</code> to <code>"X.X.X"</code></li>
</ul>
</li>
<li>Commit the version bump (try to stick to the provided commit message template)<ul>
<li>If you used the correct branch name you should be able to use this URL, after changing the X.X.X: <code>https://github.com/TeamNewPipe/NewPipe/pull/new/release-X.X.X</code></li>
<li>Once you have created the PR, note down its number (from now on called <code>PR_NUMBER</code>)</li>
<li>In case some issue would be fixed when the release PR is merged, link them using the "Development" tab on the right, or add a "Fixes #...." in the PR description</li>
<li><em>Check out <ahref="https://github.com/TeamNewPipe/NewPipe/pull/8231">#8231</a> for reference</em></li>
</ul>
<h2id="creating-the-issue">Creating the issue</h2>
<ul>
<li>Create an issue<ul>
<li>Click <ahref="https://github.com/TeamNewPipe/NewPipe/issues/new">here</a> to open one without a template</li>
</ul>
</li>
<li>The issue title should be "Release vX.X.X (please TEST!)"</li>
<li>The issue should have some sections, in the same order as provided below, with <code>##</code> before titles</li>
<li>The <code>## Testing for regressions</code> section should contain the following lines; more information about how to obtain the APK are given at <ahref="#testing-apks">Testing APKs</a></li>
<li>An optional <code>## TODO</code> section should contain a list of things that still need to be done before releasing, for example regressions that need to be fixed, or a reminder to merge the Weblate changelogs before releasing (use <code>- [ ]</code> to create checkbox lists)</li>
<li>The <code>## NewPipeExtractor version</code> section should contain a link to the NewPipeExtractor release this new NewPipe version will ship with (i.e. the one set in <ahref="#creating-the-release-branch">Creating the release branch</a>); choose one of these lines as a template</li>
</ul>
<pre><codeclass="language-md">This version of NewPipe will ship with [NewPipeExtractor version NPE_VERSION](https://github.com/TeamNewPipe/NewPipeExtractor/releases/tag/NPE_VERSION)
This version of NewPipe will ship with [NewPipeExtractor commit FIRST_7_DIGITS_OF_NPE_COMMIT](https://github.com/TeamNewPipe/NewPipeExtractor/commit/NPE_COMMIT)
</code></pre>
<ul>
<li>Create the <code>App changelog</code> section using the template below. Copy the draft Markdown changelog <ahref="https://github.com/TeamNewPipe/NewPipe/releases">kept on GitHub</a> (you finalized it earlier in <ahref="#create-a-changelog">Create a changelog</a>) to the clipboard and paste it where specified below (make sure to leave a newline above, otherwise Markdown breaks):</li>
<p>The first time you open the release issue, and then each time some changes are made to the release PR, you should provide a debug APK in the <code>## Testing for regressions</code> section.</p>
<ul>
<li>Wait for the Continuous Integration (CI) to finish testing the PR, then download the resulting debug APK artifact from the "Checks" tab</li>
<li>Rename it to <code>NewPipe_vX.X.X_RC1_debug.apk</code> where <code>RC1</code> should be incremented to <code>RC2</code> and so on each time a new APK is provided</li>
<li>Zip it and make sure the <code>.zip</code> file has the same name as the <code>.apk</code> it contains</li>
<li>Upload it in the issue description, replacing the <code>...</code> placeholder used above</li>
</ul>
<p>Sometimes it might be needed to also provide a release APK. In this case follow the same steps as above, with these differences:</p>
<ul>
<li>Make sure you are on the <code>release-X.X.X</code> branch</li>
<li>Build the <strong>release</strong> APK yourself in Android Studio and sign it with your keys<ul>
<li><em>Temporarily</em> edit the <code>app/build.gradle</code> file and add <code>System.properties.put("packageSuffix", "vX_X_X")</code> at the top of the <code>android -> buildTypes -> release</code> block, which ensures that the application has a different package name than the official one</li>
<li>Build and sign an APK via "Build -> Generate Signed Bundle / APK..."</li>
<li>Add a line to the <code>## Testing for regressions</code> section, of this form: <code>Release APK (built and signed by @YOUR_GITHUB_USERNAME): ...</code></li>
<h2id="taking-care-of-regressions-quickfixes">Taking care of regressions (quickfixes)</h2>
<p>The release issue and pull request should stay open for <strong>roughly one week</strong>, so that people can test the provided APKs and give feedback. If a <em>regression</em> is reported by some user, it should possibly be solved before releasing, otherwise the app would become more broken after each release. A <em>regression</em> is a bug now present in some code that used to run well in the last release, but was then modified in this release (supposedly to fix something else) and is now broken. So the following do not classify as regressions: some videos stop working because YouTube made some changes; the newly introduced big feature XYZ is still not perfect and has some bugs; a random crash reproducible also on previous versions... You get the point. Before releasing, try to fix any regressions that are reported, but avoid fixing non-regressions, since those should be treated with the same care and attention as all other issues. As a Release Manager, you might be required to fix regressions, so plan your release at a time when you are available.</p>
<p>Pull requests fixing regressions should target the <code>release-X.X.X</code> branch, not the <code>dev</code> branch! When merging those PRs, also provide a new Release Candidate APK.</p>
<h2id="finally-merging-the-pull-request">Finally merging the pull request</h2>
<p>Once enough time has passed and all regressions and TODOs have been solved, you can proceed with the actual release. The following points include merging weblate changes again.</p>
<ul>
<li>In the local repository, check out the release branch and make sure it is up-to-date with the remote<ul>
<p>Now on the remote <code>master</code> branch there is the release code which you need to turn into an APK.</p>
<ul>
<li>In the local repository, check out the <code>master</code> branch and make sure it is up-to-date with the remote<ul>
<li><code>git checkout master</code></li>
<li><code>git pull origin master</code></li>
</ul>
</li>
<li>Open the local project in Android Studio</li>
<li>Run the Gradle <code>clean</code> task using Android Studio's interface, in order to clean up temporary/cache files that may interfere with reproducible builds<ul>
<li>Double press Ctrl, type <code>gradle clean</code>, press Enter</li>
</ul>
</li>
<li>Make sure leftover files from building RC releases are actually removed, in order to avoid confusion<ul>
<li><code>rm -rf ./app/release</code></li>
</ul>
</li>
<li>Run the Gradle <code>assembleRelease</code> task using Android Studio's interface: it will start the process of building an unsigned APK<ul>
<li>Double press Ctrl, type <code>gradle assembleRelease</code>, press Enter</li>
</ul>
</li>
<li>After a while you should find the APK under <code>./app/build/outputs/apk/release/app-release-unsigned.apk</code></li>
<p>Currently @TheAssassin is the only holder of NewPipe's APK signing keys. Therefore you should send the unsigned APK to him, after which he will sign it and send it back to you. He will also then publish the signed APK in NewPipe's F-Droid repo.</p>
<ul>
<li>Rename <code>app-release-unsigned.apk</code> to <code>NewPipe_vX.X.X.apk</code></li>
<li>Generate a signature for the APK file<ul>
<li><code>gpg -b NewPipe_vX.X.X.apk</code> will generate <code>NewPipe_vX.X.X.apk.sig</code></li>
<li>It will also output 'using "FINGERPRINT" as default secret key for signing'; keep track of the <code>FINGERPRINT</code> part</li>
</ul>
</li>
<li>Send an email to @TheAssassin and attach both <code>NewPipe_vX.X.X.apk</code> and <code>NewPipe_vX.X.X.apk.sig</code></li>
<li>If @TheAssassin does not already know it, send him your PGP key <code>FINGERPRINT</code> you obtained before<ul>
<li>You should not send it using email this time, but using another service through which @TheAssassin can be almost sure it is really you (this is a sort of 2FA)</li>
<li>For example, you can send it on the IRC group, or create a GitHub gist with the fingerprint and then give that link to @TheAssassin</li>
</ul>
</li>
<li>Notify him on IRC that you have sent him an email</li>
<li>He will send you back the signed APK</li>
<li>Make sure its name is still <code>NewPipe_vX.X.X.apk</code> (rename if it's not the case)</li>
<li>Install it on your device to see if everything went well (note that installation will work only if your currently installed version of newpipe comes from NewPipe's F-Droid repo or GitHub)</li>
<li>Tell @TheAssassin to "push the buttons", i.e. publish the signed APK in NewPipe's F-Droid repo.</li>
<li>Attach the signed APK @TheAssassin sent you</li>
<li>Publish the release</li>
<li>Profit :-D</li>
</ul>
<h2id="blog-post">Blog post</h2>
<p>The blog post writers need an up-to-date list of merged PRs numbered in chronological order. This is so that they can keep track of what changes have already been detailed in the draft blog post, and which ones still need to be added. So make sure that there is always at least one up-to-date "master copy" of the draft release notes available for them to review.</p>
<p>The blog post should ideally be published before the GitHub release is made (so that the link to it works!), but in case of some delay, it is fine to let the blog post come later. It is far more important to get the release into users' hands sooner.</p>
<ul>
<li>In order for the blog post to be published, ask @TheAssassin to "press the buttons" again</li>
<li>Once the blog post is ready, add this block of text on top of the release notes on GitHub:
<code>[:arrow_right: :arrow_right: :arrow_right: Read the blog post :arrow_left: :arrow_left: :arrow_left:](LINK_TO_BLOG_POST)</code></li>
<ahref="../06_releasing/"class="btn btn-neutral float-left"title="Releasing a New NewPipe Version"><spanclass="icon icon-circle-arrow-left"></span> Previous</a>
Built with <ahref="https://www.mkdocs.org/">MkDocs</a> using a <ahref="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> provided by <ahref="https://readthedocs.org">Read the Docs</a>.
