From 93331843929974d979e0b030dc3745c93668d0c9 Mon Sep 17 00:00:00 2001 From: Rowen S Date: Mon, 25 Nov 2024 17:42:25 -0500 Subject: [PATCH] Add dbgsym explainer and note in workstation release management. --- docs/apt_repo.rst | 27 +++++++++++++++++++++++++ docs/release_management.rst | 2 +- docs/workstation_release_management.rst | 2 +- 3 files changed, 29 insertions(+), 2 deletions(-) diff --git a/docs/apt_repo.rst b/docs/apt_repo.rst index 838666b7..b8aace61 100644 --- a/docs/apt_repo.rst +++ b/docs/apt_repo.rst @@ -47,3 +47,30 @@ All `SecureDrop Client `_ c .. _SecureDrop 0.3.10: https://github.com/freedomofpress/securedrop/blob/c5b4220e04e3c81ad6f92d5e8a92798f07f0aca2/changelog.md .. _apt.freedom.press: https://apt.freedom.press .. _`Source Offer`: https://github.com/freedomofpress/securedrop/blob/develop/SOURCE_OFFER + + +.. _dbgsym-packages: + +About dbgsym packages +--------------------- + +A +`debug symbols package `_ is a Debian package +that includes static debug symbols and allows for generating a backtrace or other +diagnostic information in the event of a crash, for example +`with gdb `_. These packages +have a ``-dbgsym.deb`` suffix on Debian, and a ``-dbgsym.ddeb`` suffix (which we +`rename `_ +to to ``-dbgsym.deb`` for consistency) on Ubuntu. These packages are generated +during the build process for components that include compiled binaries, such as +for SecureDrop components with Rust or C code, and they do not make any +other changes (i.e, they do not enable debug logs). + +When building non-kernel production Debian packages, follow the relevant Release Management +documentation to commit the dbgsym packages along with the regular production +packages. These packages are automatically placed in a separate repo component (``main-debug``) in +`securedrop-apt-prod `_. + +Currently, we publish dbgsym packages for: ``securedrop-app-code`` (core), +``securedrop-client``, ``securedrop-proxy`` (workstation). Kernel builds also +generate dbgsym packages, but they are not published due to their prohibitive size. diff --git a/docs/release_management.rst b/docs/release_management.rst index 5d761abb..8ea7a3d7 100644 --- a/docs/release_management.rst +++ b/docs/release_management.rst @@ -233,7 +233,7 @@ Release Process `securedrop-apt-prod `_ repository, create a branch from ``main`` called ``release``. #. In your local branch, commit the built packages to the ``core/focal`` - directory. + directory. Include all .deb packages, including ``-dbgsym`` packages. ``-dbgsym`` packages belong in the ``main-debug`` component repo. See :ref:`Notes on dbgsym-packages ` for more information. #. Run the ``tools/publish`` script. This will create the ``Release`` file. #. Commit the changes made by the ``tools/publish`` script. #. Push your commits to the remote ``release`` branch. This will trigger an diff --git a/docs/workstation_release_management.rst b/docs/workstation_release_management.rst index faaa69ba..087da012 100644 --- a/docs/workstation_release_management.rst +++ b/docs/workstation_release_management.rst @@ -92,7 +92,7 @@ Step 5: Build and deploy the packages to ``apt-qa`` make build-debs 3. Save and publish :doc:`build metadata `. -4. Add your packages to a new branch called ``release`` in https://github.com/freedomofpress/securedrop-apt-prod. Include all .deb packages (including ``-dbgsym`` packages) built by the client. +4. Add your packages to a new branch called ``release`` in https://github.com/freedomofpress/securedrop-apt-prod. Include all .deb packages built by the client, including ``-dbgsym`` packages. ``-dbgsym`` packages belong in the ``main-debug`` component repo. See :ref:`Notes on dbgsym-packages ` for more information. 5. Update the apt repo distribution files by running ``./tools/publish`` and push those changes to the ``release`` branch as well. 6. :ref:`Regenerate and sign the apt release file` or ask another maintainer to do this. The packages will now be installable from https://apt-qa.freedom.press. 7. Open a PR to merge the ``release`` branch into ``main``.