Document branch names and the ppa system (#96)

* Document branch names and the ppa system * Fix code-blocks * Reduce ambiguity * Fix double words * build not commit * Corrections about ubports.depends * Add information on how the name of the branch translates to the name of the ppa * Readability, spelling, markup changes
ubports · Apr 5, 2018 · 898f165 · 898f165
1 parent 1718884
commit 898f165
Show file tree

Hide file tree

Showing 3 changed files with 63 additions and 0 deletions.
diff --git a/about/process/branch-naming.rst b/about/process/branch-naming.rst
@@ -0,0 +1,53 @@
+Branch-naming convention
+========================
+
+Our branch-naming conventions ensure that software can be built by our CI and tested easily by other developers.
+
+Every Git repository's README file should state which branch-naming convention is used and possible deviations from the norm.
+
+Click-Packages
+--------------
+
+Software that is exclusively distributed as a click-package (and not also as a deb) only uses one ``master`` branch that is protected. Separate temporary development branches with arbitrary descriptive names can be created and merged into master when the time comes. For marking and archiving milestones in development history, ideally Git tags or GitHub releases should be used.
+
+Deb-Packages
+------------
+
+To make most efficient use of our CI system, a special naming convention for git-branches is used.
+
+For pre-installed Ubuntu Touch components, deb-packages are used wherever possible. This includes Core Apps, since they can still be independently updated using click-package downloads from the OpenStore. This policy allows us to make use of the powerful Debian build system to resolve dependencies.
+
+Every repository that uses this convention will have branches for the actively supported Ubuntu releases referenced by their codenames (``bionic``, ``xenial``, ``vivid``, etc.). These are the branches that are built directly into the corresponding images and published on :doc:`repo.ubports.com <ppa>`. If no separate versions for the different Ubuntu bases are needed, the repository will just have one ``master`` branch and the CI system will still build versions for all actively supported releases and resolve dependencies accordingly.
+
+Branch-extensions
+^^^^^^^^^^^^^^^^^
+
+To build and publish packages based on another repository, an extension in the form of  ``xenial_-_some-descriptive_extension`` can be used. The CI system will then resolve all dependencies using the ``xenial_-_some-descriptive_extension`` branch of other repositories or fall back on the normal ``xenial`` dependencies, if that doesn't exist. These special dependencies are not built into the image but still pushed to  on :doc:`repo.ubports.com <ppa>`.
+
+Multiple branch extensions can be chained together in the form of ``xenial_-_dependency-1_-_dependency-2_-_dependency-3``. This means that the CI system will look for dependencies in the following repositories:
+
+.. code-block:: text
+
+    xenial
+    xenial_-_dependency-1
+    xenial_-_dependency-1_-_dependency-2
+    xenial_-_dependency-1_-_dependency-2_-_dependency-3
+
+.. note::
+
+    There is no prioritization, so the build system will always use the package with the highest version number or the newest build if the version is equal.
+
+Dependency-file
+^^^^^^^^^^^^^^^
+
+For complex or non-linear dependencies, a ``ubports.depends`` file can be created in the root of the repository to specify additional dependencies. The branch name will be ignored if this file exists.
+
+.. code-block:: text
+
+    xenial
+    xenial_-_dependency-1_-_dependency-2_-_dependency-3
+    xenial_-_something-else
+
+.. note::
+
+    The ``ubports.depends`` file is an **exclusive list**, so the build system will not resolve dependencies linearly like it does in a branch name! Every dependency has to be listed. You will almost always want to include your base release (i.e. ``xenial``).
diff --git a/about/process/index.rst b/about/process/index.rst
@@ -12,3 +12,5 @@ This section of the documentation details standardized processes for different t
 
     issue-tracking
     release-schedule
+    ppa
+    branch-naming
diff --git a/about/process/ppa.rst b/about/process/ppa.rst
@@ -0,0 +1,8 @@
+repo.ubports.com
+================
+
+This is the package archive system for UBports projects. It hosts various PPAs containing all deb-components of Ubuntu Touch. New PPAs can be created dynamically by the CI server using a special :doc:`git-branch naming convention <branch-naming>`.
+
+The name of the branch translates literally to the name of the PPA: ``http://repo.ubports.com/dists/[branch name]``
+
+Non-standard PPAs (i.e. not ``xenial``, ``vivid`` or ``bionic``) are kept for three months. In case they need to be kept for a longer time, a file with the name ``ubports.keep`` can be created in the root of the repository, containing the date until which the PPA shall be kept open in the form of **YYYY-MM-dd**. If this file is empty, the PPA will be kept for two years after the last build.