Commit 57392a51 authored by David Boddie's avatar David Boddie
Browse files

Add sections about core packaging workflow

parent e4978ff5
......@@ -16,4 +16,4 @@ and patches.
Contact/Contributing
Contact/Contributing/Translations
Contact/Issues
Contact/Package_Building
Contact/Core_Workflow
.. _core_package_base_packages:
Adding Base Packages
====================
Packages built by the Continuous Integration (CI) system can be included as base packages in the Librem 5 system image, which means that they are pre-installed on the phone.
.. contents::
:local:
Packaging Requirements
----------------------
Only packages available in PureOS can be included in the system image for the Librem 5. See the :ref:`core_package_uploading` guide for information about creating packages for PureOS.
Base Packages
-------------
The base packages on the phone are defined in the `librem5-base`_ repository, which is used to generate metapackages -- packages that are used to group packages into collections for convenient installation. The CI system `builds system images <Image Builds_>`_ that include some of these metapackages pre-installed.
To ensure that a package is installed, it needs to be included in one of the `librem5-base`_ metapackages.
.. include:: /links.txt
Core Workflow
=============
Software that is supplied with the phone is built using a process that aims to automate as much as possible. The process is summarized in the overview below.
.. toctree::
:maxdepth: 1
Package_Building
Uploading_to_PureOS
Adding_Base_Packages
Overview
--------
Software that should be included in system images or supplied as Debian packages is built and packaged using a multi-stage process, using different systems to test the software at each stage. The following steps describe how software is processed:
#. The developer creates Debian packaging for the software, testing it locally to ensure that it works.
#. The developer adds information about the public repository containing the software to the `deb-build-jobs`_ repository via a merge request. This is covered by the :ref:`core_package_building` section of this guide.
#. The developer tags a release using a signed git tag to ensure that it is published in the PureOS package repository. This is covered by the :ref:`core_package_uploading` section of this guide.
#. The Continuous Integration (CI) server runs the build scripts from the `deb-build-jobs`_ repository to produce packages.
#. Packages for signed releases are included in the PureOS package repository.
#. The Librem 5 system image is built using software from the repository using information from the `librem5-base`_ repository.
Packages can be downloaded from the page containing `Debian Package Builds for the Librem 5`_ and are also available from the `CI scratch repository`_.
Packages that need to be included in the Librem 5 system image must be added to the package lists in the ``librem5-base`` repository. This is described in the :ref:`core_package_base_packages` section.
.. include:: /links.txt
Package Building
================
.. _core_package_building:
.. note:: This section is mostly useful for core contributors.
Core Package Building
=====================
Some components are built by the Continuous Integration (CI) system as Debian packages to enable convenient distribution, installation and upgrade. This requires that the components have Debian packaging files that can be used by the CI system to build packages.
......@@ -15,7 +15,9 @@ Build Jobs and Packages
Information about the components to be packaged is held in the `deb-build-jobs`_ repository, where the ``jobs.yml`` file contains metadata for each of them. This is extracted and passed to a script that runs the `git-buildpackage`_ tool to perform the package build.
The packages built by the CI system are published on the `Debian Package Builds for the Librem 5`_ page and most of them are also published in the `Librem 5 scratch apt repository`_.
The packages built by the CI system are published on the `Debian Package Builds for the Librem 5`_ page and most of them are also published in the `Librem 5 scratch package repository`_.
Build reports for packages processed by the CI system are published on the `librem5-builds`_ mailing list.
Metadata Format
---------------
......
.. _core_package_uploading:
Uploading Packages to PureOS
============================
Packages built by the Continuous Integration (CI) system can be published in the PureOS package repository. Only specific releases that are specially tagged are uploaded to the repository.
.. contents::
:local:
Packaging Requirements
----------------------
Only packages built using the CI system can be submitted to the package repository for the phone. See :ref:`core_package_building` for instructions describing how to submit packages to the CI system.
If you are both the developer and packager of the software, specify ``amber-phone`` as the suite in the ``debian/changelog`` file for the latest release. For example::
phosh (0.1.0) amber-phone; urgency=medium
This indicates the suite where the package will be published.
Tag the Release with a Signed Tag
---------------------------------
Each package that needs to be made available from the PureOS package repository must be generated from a commit that is tagged with a signed git tag by the developer.
Upstream Packaging
~~~~~~~~~~~~~~~~~~
For packages where the packager is also the upstream developer, the release commit should be tagged with a signed tag as in this example:
.. code:: bash
git tag -s -m'phosh v0.1.0' v0.1.0
Here, ``phosh`` is the name of the package, as given in the ``debian/changelog`` file. The version must correspond to the latest package version, so ``v0.1.0`` corresponds to version 0.1.0 in the changelog::
phosh (0.1.0) amber-phone; urgency=medium
Ensure that the version numbers match and that the tag is prefixed with ``v`` both in the tag itself and in the message passed using the ``-m`` option.
Publish the tag in the publicly available repository for the software so that the CI system can find it. This must be the same repository specified in the ``jobs.yml`` file in the `deb-build-jobs`_ repository. The CI system will pull the signed tag automatically.
Uploading Packages
------------------
The CI system takes care of uploading packages to the PureOS package repository where they can be found using the `PureOS package search`_ tool. If a package does not appear when one is expected, check the messages in the `librem5-builds`_ mailing list to make sure that the package was built successfully.
Further Reading
---------------
See the `Librem5 pureos amber-phone uploads`_ note for more details about creating and preparing packages for upload to the PureOS package repository.
.. _`Librem5 pureos amber-phone uploads`: https://source.puri.sm/snippets/138
.. include:: /links.txt
......@@ -3,6 +3,7 @@
.. _`AppStream`: https://www.freedesktop.org/software/appstream/docs/
.. _`AppStream metadata`: https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html
.. _`Building your first Flatpak`: http://docs.flatpak.org/en/latest/first-build.html
.. _`CI scratch repository`: https://ci.puri.sm/dists/scratch/
.. _`community/librem-5`: https://matrix.to/#/#community-librem-5:talk.puri.sm
.. _`community/librem-5-apps`: https://matrix.to/#/#community-librem-apps:talk.puri.sm
.. _`community/librem-5-devkit`: https://matrix.to/#/#librem-5-devkit:talk.puri.sm
......@@ -105,6 +106,7 @@
.. _HdyTitleBar : https://developer.puri.sm/projects/libhandy/unstable/HdyTitleBar.html
.. _`How to create a GTK application using Python`: https://belmoussaoui.com/2019/05/13/how-to-create-a-gtk-application-using-python-part-1/
.. _`iio-sensor-proxy`: https://github.com/hadess/iio-sensor-proxy
.. _`image-builder`: https://source.puri.sm/Librem5/image-builder/
.. _`Image Builds`: https://arm01.puri.sm/job/Images/job/Image%20Build/
.. _`journalctl man page`: https://www.freedesktop.org/software/systemd/man/journalctl.html
.. _`KDE Community`: https://www.kde.org
......@@ -120,8 +122,11 @@
.. _libhandy website : https://source.puri.sm/Librem5/libhandy
.. _`Librem 5 developer documentation repository`: https://source.puri.sm/Librem5/developer.puri.sm
.. _`Librem 5 examples project`: https://source.puri.sm/Librem5/example-apps/
.. _`Librem 5 scratch apt repository`: https://ci.puri.sm/dists/scratch/
.. _`Librem 5 user guide`: https://docs.puri.sm/Librem_5.html
.. _`Librem 5 scratch apt repository`: https://ci.puri.sm/dists/scratch/
.. _`Librem 5 scratch package repository`: https://ci.puri.sm/dists/scratch/
.. _`librem5-base`: https://source.puri.sm/Librem5/librem5-base
.. _`librem5-builds`: https://lists.community.puri.sm/pipermail/librem5-builds
.. _`librem5-devkit-tools`: https://source.puri.sm/Librem5/librem5-devkit-tools
.. _`librem5-m2-breakout repository`: https://source.puri.sm/Librem5/librem5-m2-breakout
.. _`linux-emcraft repository`: https://source.puri.sm/Librem5/linux-emcraft/
......@@ -141,6 +146,7 @@
.. _`Plasma Mobile application development`: https://docs.plasma-mobile.org/AppDevelopment.html
.. _`Issues for Plasma Mobile on Librem 5`: https://source.puri.sm/groups/Librem5/Plasma/-/issues
.. _`PureOS`: https://pureos.net
.. _`PureOS package search`: https://software.pureos.net/search_pkg
.. _`Purism FAQ`: https://puri.sm/faq
.. _`PyGObject`: https://pygobject.readthedocs.io/
.. _`PyGObject API Reference`: https://lazka.github.io/pgi-docs/
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment