newpipe-documentation/06_releasing/index.html

402 lines
24 KiB
HTML

<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="shortcut icon" href="../img/favicon.ico" />
<title>Releasing a New NewPipe Version - NewPipe Development Documentation</title>
<!-- local fonts -->
<link rel="stylesheet" href="../css/local_fonts.css" type="text/css" />
<link rel="stylesheet" href="../css/theme.css" type="text/css" />
<link rel="stylesheet" href="../css/theme_extra.css" type="text/css" />
<link rel="stylesheet" href="../css/theme_child.css" type="text/css" />
<!-- local code syntax highlighting -->
<link rel="stylesheet" href="../css/github.min.css" type="text/css" />
<link rel="stylesheet" href="../css/highlight.css" type="text/css" />
<script>
// Current page data
var mkdocs_page_name = "Releasing a New NewPipe Version";
var mkdocs_page_input_path = "06_releasing.md";
var mkdocs_page_url = null;
</script>
<script src="../js/jquery-2.1.1.min.js" defer></script>
<script src="../js/modernizr-2.8.3.min.js" defer></script>
<script src="../js/highlight.min.js"></script>
<script>hljs.initHighlightingOnLoad();</script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
<div class="wy-side-scroll">
<div class="wy-side-nav-search">
<a href=".." class="icon icon-home"> NewPipe Development Documentation
</a><div role="search">
<form id ="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" title="Type search term here" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<ul>
<li class="toctree-l1"><a class="reference internal" href="..">Welcome to the NewPipe Development Docs</a>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../00_Prepare_everything/">Before You Start</a>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../01_Concept_of_the_extractor/">Concept of the Extractor</a>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../02_Concept_of_LinkHandler/">Concept of the LinkHandler</a>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../03_Implement_a_service/">Implementing a Service</a>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../04_Run_changes_in_App/">Testing Your Changes in the App</a>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../05_Mock_tests/">Mock Tests</a>
</li>
</ul>
<ul class="current">
<li class="toctree-l1 current"><a class="reference internal current" href="./">Releasing a New NewPipe Version</a>
<ul class="current">
<li class="toctree-l2"><a class="reference internal" href="#differences-between-regular-and-hotfix-releases">Differences Between Regular and Hotfix Releases</a>
</li>
<li class="toctree-l2"><a class="reference internal" href="#regular-releases">Regular Releases</a>
<ul>
<li class="toctree-l3"><a class="reference internal" href="#feature-branching">Feature Branching</a>
</li>
<li class="toctree-l3"><a class="reference internal" href="#merging-featuresbugfixes">Merging Features/Bugfixes</a>
</li>
<li class="toctree-l3"><a class="reference internal" href="#normal-releases">Normal Releases</a>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#hotfix-releases">Hotfix Releases</a>
<ul>
<li class="toctree-l3"><a class="reference internal" href="#hotfix-branch">Hotfix Branch</a>
</li>
<li class="toctree-l3"><a class="reference internal" href="#releasing">Releasing</a>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#extractor-releases">Extractor releases</a>
</li>
<li class="toctree-l2"><a class="reference internal" href="#version-nomenclature">Version Nomenclature</a>
<ul>
<li class="toctree-l3"><a class="reference internal" href="#version-nomenclature-of-the-extractor">Version Nomenclature of the Extractor</a>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#release-notes">Release Notes</a>
<ul>
<li class="toctree-l3"><a class="reference internal" href="#changelog-file">Changelog file</a>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#publish-on-f-droid">Publish on F-Droid</a>
</li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../07_release_instructions/">Release instructions for normal releases</a>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../08_documentation/">About This Documentation</a>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../09_maintainers_view/">Maintainers' Section</a>
</li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="Mobile navigation menu">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="..">NewPipe Development Documentation</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content"><div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href=".." class="icon icon-home" aria-label="Docs"></a> &raquo;</li>
<li class="breadcrumb-item active">Releasing a New NewPipe Version</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div class="section" itemprop="articleBody">
<h1 id="releasing-a-new-newpipe-version">Releasing a New NewPipe Version</h1>
<p>This site is meant for those who want to maintain NewPipe, or just want to know how releasing works.</p>
<p><img alt="one does not simply push to master" src="../img/onedoes.jpg" /></p>
<h2 id="differences-between-regular-and-hotfix-releases">Differences Between Regular and Hotfix Releases</h2>
<p>Depending on the service, NewPipe Extractor uses web crawling or internal APIs.
Both are subject to arbitrary changes by the service providers, like YouTube, SoundCloud or PeerTube.
When they change something, NewPipe Extractor and thus NewPipe break instantly.
Therefore, maintainers need to act quickly when it happens, and reduce our downtime as
much as possible. The entire release cycle is therefore designed around this issue.</p>
<p>There is a difference between a release that introduces new features
and a release that fixes an issue that occurred because YouTube, or some other service,
changed their website (typically called a shutdown).
Let's have a look at the characteristics of a <strong>regular release</strong>,
and then the characteristics of a <strong>hotfix release</strong>.</p>
<h2 id="regular-releases">Regular Releases</h2>
<p>Regular releases are normal releases as they are done in any other app.
Releases are always stored and tagged on <strong>master</strong> branch. The latest commit on
<strong>master</strong> is always equal to the currently released version. No development is done on master.
This ensures that we always have one branch with a stable/releasable version.</p>
<h3 id="feature-branching">Feature Branching</h3>
<p>The <strong>dev</strong> branch is used for development. Pushing to <strong>dev</strong> directly, however, is not allowed,
since QA and testing should be done <em>before</em> adding something to the branch.
This ensures that the development version works as stable a possible.
In order to change something on the app, one may want to <strong>fork</strong> the dev branch
and develop the changes in their own branch (this is called feature branching).</p>
<p><img alt="feature_branching" src="../img/feature_branch.svg" /></p>
<p>Make sure that both the dev branches, as well as the master branches of the extractor
and the frontend, are compatible with each other.
If the extractor's API is modified, make sure that frontend is compatible,
or changed to become compatible, with these changes.
If the PR that should make the frontend compatible
again can not be merged, please do not merge the corresponding PR on the extractor either.
This should make sure that any developer can run his changes on the fronted at any time.</p>
<h3 id="merging-featuresbugfixes">Merging Features/Bugfixes</h3>
<p>After finishing a feature, one should open up a <strong>Pull Request</strong> to the dev branch.
From here, a maintainer can do <strong>Code review</strong> and <strong>Quality Assurance (QA)</strong>.
If you are a maintainer, please take care about the code architecture
so <strong>corrosion</strong> or <strong>code shifting</strong> can be prevented.
Please also prioritize code quality over functionality.<br />
In short: cool function but bad code = no merge. Focus on keeping the code as clean as possible.</p>
<p><img alt="merge_feature_into_dev" src="../img/merge_into_dev.svg" /></p>
<p>An APK for <strong>testing</strong> is provided by GitHub Actions for every PR.
Please ensure that this APK is tested thoroughly to prevent introducing regressions.
Testing features needs to take into account that NewPipe is used on a brought variety
of Android versions from KitKat to the latest, on custom ROMs like Lineage OS, CalyxOS or /e/
and different devices like phones, tablets and TVs.</p>
<p>Sometimes, the content of a PR changes over the time.
Modify the PR's title if it does not represent the introduced changes anymore.
After a maintainer merged the new feature into the dev branch,
they should add the PR's title or a summary of the changes into the <a href="#release-notes">release notes</a>.</p>
<h3 id="normal-releases">Normal Releases</h3>
<p>Once there are enough changes, and the maintainers believe that NewPipe is ready
for a new version, they should prepare a new release.<br />
Be aware of the rule that a release should never be done on a Friday.
For NewPipe, this means: <strong>Don't do a release if you don't have time for it!!!</strong></p>
<p>By following the steps listed in <a href="../07_release_instructions">Release instructions</a>, you can publish a stable version of NewPipe.</p>
<h2 id="hotfix-releases">Hotfix Releases</h2>
<p><img alt="this_is_fine" src="../img/could_not_decrypt.png" /></p>
<p>As aforementioned, NewPipe heavily relies on external components and might break at a random point of time.
In order to keep the NewPipe's downtime as low as possible, when such a shutdown happens,
we allow <strong>hotfixes</strong>.</p>
<ul>
<li>A hotfix allows work on the master branch instead of the dev branch.</li>
<li>A hotfix MUST <strong>NOT</strong> contain any features or unrelated bugfixes.</li>
<li>A hotfix may only focus on fixing what caused the shutdown.</li>
</ul>
<h3 id="hotfix-branch">Hotfix Branch</h3>
<p>Hotfixes work on the master branch.
The dev branch has experimental changes that might have not been tested properly enough to be released,
if at all. The master branch should always be the latest stable version of NewPipe.
If the master branch breaks due to a shutdown, you should fix the master branch.
Of course, you are not allowed to push to master directly,
so you need to create a <strong>hotfix</strong> branch.
<em>If someone else is pushing a hotfix into master, and it works this can be considered as hotfix branch as well.</em></p>
<p><img alt="hotfix_branch" src="../img/hotfix_branch.svg" /></p>
<h3 id="releasing">Releasing</h3>
<p>If you fixed the issue and found it to be tested and reviewed well enough, you may publish a new version.
You don't need to undergo the full release procedure of a regular release, which takes too much time.
Keep in mind that if the hotfix might turn out to be broken after release, you should release another hotfix.
It is important to release quickly for the sake of keeping NewPipe alive, and after all,
a slightly broken version of NewPipe is better than a non-functional version ¯\_(ツ)_/¯.
Here's what you do when releasing a hotfix:</p>
<ol>
<li>Merge the corresponding pull request in the extractor.</li>
<li><a href="#extractor-releases">Publish the new extractor version</a>.</li>
<li>Update the extractor version in the app's <code>build.gradle</code> file.</li>
<li>Create a new release draft and put some info on the fix into the <a href="#release-notes">release note</a>.</li>
<li>Copy the release notes into the fastlane directory to create a <a href="#changelog-file">changelog file</a>.</li>
<li>Increment the <strong>small minor</strong> version number and the <code>versionCode</code>.</li>
<li>Generate a release APK (<code>gradlew assembleRelease</code>) and sign it (or get it signed by one of the other maintainers).</li>
<li>Add the signed APK to the GitHub release notes.</li>
<li>Click "Publish Release" .</li>
<li><a href="#publish-on-f-droid">Publish the new version on F-Droid</a>.</li>
<li>Merge the changes from <strong>master</strong> into <strong>dev</strong>.</li>
<li><a href="https://github.com/TeamNewPipe/website/blob/master/_includes/release_data.html">Update the changelog for the website</a>.</li>
</ol>
<p><img alt="rebase_back_hotfix" src="../img/rebase_back_hotfix.svg" /></p>
<h2 id="extractor-releases">Extractor releases</h2>
<p>In general, the release process for extractor versions is not that complicated compared to app releases.
The extractor has (in difference to the app) a decent test coverage.
Additionally, the latest extractor version is typically tested in the app's latest <strong>dev</strong> version.
Therefore, a long test phase is not needed when creating extractor releases.</p>
<p>To create a new <a href="#version-nomenclature-of-the-extractor">extractor version</a>, update the <strong>version</strong> in the extractor's <code>build.gradle</code> file
as well as the version names in the README.
Merge the <strong>dev</strong> branch into <strong>master</strong>.
The same that applies the app's <a href="#release-notes">release notes</a> also applies to the extractor's release notes.</p>
<p>When publishing an extractor release via GitHub on the <strong>master</strong> branch,
a new <a href="https://teamnewpipe.github.io/NewPipeExtractor/javadoc/">JavaDoc version</a>
is generated and published automatically.
Pleas keep an eye on the GitHub Action which is responsible for that.
If changes in that release introduced invalid JavaDoc, the build fails and needs to be fixed.
For this reason, you should check locally if there are any problems with the JavaDoc generation before publishing the new version.</p>
<h2 id="version-nomenclature">Version Nomenclature</h2>
<p>The version nomenclature of NewPipe is simple.</p>
<ul>
<li><strong>Major</strong>: The <strong>major</strong> version number (the number before the first dot) was 0 for years.
The reason for this changed over time. First, I wanted this number to
switch to 1 once NewPipe was feature complete.
Now, I rather think of incrementing this number to 1 once we can ensure that NewPipe runs stable
(part of which this documentation should help).
After this, well, God knows what happens if we ever reach 1. ¯\_(ツ)_/¯ </li>
<li><strong>Minor</strong>: The <strong>minor</strong> version number (the number after the first dot)
will be incremented if there is a major feature added to the app.</li>
<li><strong>Small Minor</strong>: The small minor (the number after the second dot)
is incremented when bug fixes or minor features are added to the app.</li>
</ul>
<h4 id="version-nomenclature-of-the-extractor">Version Nomenclature of the Extractor</h4>
<p>Previously, the extractor was released together with the app,
therefore the version number of the extractor was identical to the one of NewPipe itself.</p>
<p>We try to combine efforts to make NewPipe Extractor more independent of the app.
The extractor is used by multiple other applications
and therefore releasing extractor updates should not be coupled to app releases.
However, maintainers need to keep an eye on making the app compatible with extractor changes.</p>
<h2 id="release-notes">Release Notes</h2>
<p>Release notes should tell what was changed in the new version of the app.
The release notes for NewPipe are stored in the
<a href="https://github.com/TeamNewPipe/NewPipe/releases">GitHub draft for a new release</a>.
When a maintainer wants to add changes to the release notes,
but there is no draft for a new version, they should create one.</p>
<p>Changes can be categorized into five basic types:</p>
<ul>
<li><strong>New</strong>: New features that got added to the app.</li>
<li><strong>Improved</strong>: Improvements to the app or existing features</li>
<li><strong>Fixed</strong>: Bugfixes</li>
<li><strong>Translation</strong>: New translations</li>
<li><strong>Development</strong>: Changes which address things "under the hood",
which do not have any recognizable effect to the user; e.g. dependency updates or changes to the build process</li>
</ul>
<p>When adding a PR to the release notes, increase the PR counter at the top of the draft
and put the number before the PR summary / title.
This helps the blog post authors to keep easily track of new PRs.
Remove the numbers before publishing a new version :)</p>
<p>If there is a blog post covering the changes in more detail,
make sure to link it on the top of the release notes.
It would be a pity, if only a few people read the blog post
after our wonderful writers put so much effort into creating it.</p>
<h3 id="changelog-file">Changelog file</h3>
<p>Maintainers need to provide a changelog file for each release.
A changelog file is used by F-Droid to give a quick summary of the most important changes for a release.
This file is placed in the
<a href="https://github.com/teamnewpipe/newpipe/tree/dev/fastlane/metadata/android/en-US/changelogs"><code>/fastlane/metadata/android/en-US/changelogs</code></a>
directory and named <code>&lt;versionCode&gt;.txt</code> (whereas <code>&lt;versionCode&gt;</code> is the version code of the incoming release).
Changelog files <em>must not</em> exceed 500 bytes.
Be aware that the changelog is translated into multiple languages.
A changelog written in English which almost hits 500 bytes can hardly be translated completely within this limit.
This causes troubles for translators, because Weblate enforces the 500 bytes limit, too.
For this reason it is recommended to keep the changelog at 400 bytes.</p>
<p>When creating the changelog file be aware of changes which were done in the extractor as well.<br />
Before pushing the changelog to NewPipe's repo, ask other maintainers to review it.<br />
After pushing the changelog to NewPipe's GitHub repo, <a href="../09_maintainers_view#update-weblate">updating Weblate</a> is necessary.
This enables translators to work on localized versions of the changelog before a release is tagged and published.</p>
<h2 id="publish-on-f-droid">Publish on F-Droid</h2>
<p>NewPipe is and supports open source software.
For this reason, the preferred way to distribute the app is <a href="https://f-droid.org">F-Droid</a>.
F-Droid is a catalogue of FOSS apps and also comes with an Android client which handles app updates.
There are two ways to install NewPipe via F-Droid.</p>
<ol>
<li><strong>Through the main F-Droid repository</strong><br />
NewPipe's metadata file can be found in F-Droid's data repository on GitLab:
<a href="https://gitlab.com/fdroid/fdroiddata/-/blob/master/metadata/org.schabi.newpipe.yml">https://gitlab.com/fdroid/fdroiddata/-/blob/master/metadata/org.schabi.newpipe.yml</a><br />
This file is automatically updated by a bot when a new release is published on GitHub.
It can take a few days until all new apps on F-Droid are built, signed and published.<br />
<a href="https://f-droid.org/docs/Reproducible_Builds/">F-Droid also supports reproducible builds</a>.
Reproducible builds or deterministic builds allow someone else to retrieve the exact same binary
as we get when building the app (except the signing of course).<br />
When the reproducible build feature is enabled for an app in F-Droid, they compare their binary to one provided by the author.
If both are identical, F-Droid does not only publish the binary signed by themselves, but also the one signed by the author.<br />
Currently, NewPipe's builds are not deterministic, and we therefore cannot use that feature.
Once the builds are deterministic again, the following steps need to be done to publish a new version on F-Droid:<ol>
<li><a href="https://f-droid.org/docs/Installing_the_Server_and_Repo_Tools/">Install <code>fdroidserver</code> on your device</a>.</li>
<li>Clone the F-Droid Data repo from <code>https://gitlab.com/fdroid/fdroiddata</code></li>
<li>Add the new version to <code>metadata/org.schabi.newpipe.yml</code></li>
<li>Run <code>fdroid signatures /path/to/newpipe.apk</code> on the signed APK from within the repo.</li>
<li>Create a MR on GitLab.
An example commit containing all required changes can be found <a href="https://gitlab.com/fdroid/fdroiddata/-/commit/393bbb756d5bed4134eb147f411a9d9aa1d47386">here</a>.</li>
</ol>
</li>
<li><strong>Through NewPipe's F-Droid repository</strong><br />
F-Droid needs
NewPipe's own F-Droid repo is available at <a href="https://archive.newpipe.net/fdroid/repo/?fingerprint=E2402C78F9B97C6C89E97DB914A2751FDA1D02FE2039CC0897A462BDB57E7501">https://archive.newpipe.net/fdroid/repo</a>
It is updated and maintained by <a href="https://github.com/TheAssassin">@TheAssassin</a>.</li>
</ol>
</div>
</div><footer>
<div class="rst-footer-buttons" role="navigation" aria-label="Footer Navigation">
<a href="../05_Mock_tests/" class="btn btn-neutral float-left" title="Mock Tests"><span class="icon icon-circle-arrow-left"></span> Previous</a>
<a href="../07_release_instructions/" class="btn btn-neutral float-right" title="Release instructions for normal releases">Next <span class="icon icon-circle-arrow-right"></span></a>
</div>
<hr/>
<div role="contentinfo">
<!-- Copyright etc -->
</div>
Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<div class="rst-versions" role="note" aria-label="Versions">
<span class="rst-current-version" data-toggle="rst-current-version">
<span><a href="../05_Mock_tests/" style="color: #fcfcfc">&laquo; Previous</a></span>
<span><a href="../07_release_instructions/" style="color: #fcfcfc">Next &raquo;</a></span>
</span>
</div>
<script src="../js/jquery-3.6.0.min.js"></script>
<script>var base_url = "..";</script>
<script src="../js/theme_extra.js"></script>
<script src="../js/theme.js"></script>
<script src="../search/main.js"></script>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>