Add dbgsym explainer and note in workstation release management.

docs/apt_repo.rst

@@ -47,3 +47,30 @@ All `SecureDrop Client <https://github.com/freedomofpress/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 <https://wiki.debian.org/DebugPackage>`_ 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 <https://wiki.debian.org/HowToGetABacktrace/#Running_gdb>`_. These packages
+have a ``-dbgsym.deb`` suffix on Debian, and a ``-dbgsym.ddeb`` suffix (which we 
+`rename <https://github.com/freedomofpress/securedrop/blob/b7bda4fe7badd5267a829f5bfe243fd13db9178e/builder/build-debs-securedrop.sh#L35-L37>`_
+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 <https://github.com/freedomofpress/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.

docs/release_management.rst

@@ -233,7 +233,7 @@ Release Process
    `securedrop-apt-prod <https://github.com/freedomofpress/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 <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

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 <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 <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``.