README.source

## Extensions sources

The extensions sources are managed as meson subprojects, in order to be able
to maintain the extensions independently, but at the same time to provide and
single point of control of their versions (the ./subprojects/*.wrap files).

## Tracking vendored sources
 - Extensions code is tracked using meson wrap files located in
   `subprojects/*.wrap` files.
 - Each wrap file must point to the extension git repository (or ubuntu fork)
 - Wrap files MUST reference a specific `revision` that points to an upstream
   git tag or commit SHA. Branch names or HEAD are not valid values.
   This is ensured by a CI job.
 - Patches can be added using the wrap system in:
   - subprojects/packagefiles/patches/<extension>/*.patch

## Package sources builds

As per this, this package sources are meant to be generated using
gbp-buildpackage as it allows to define pre-build hooks that are required to
generate the full source package.

So:
 - This relies on gbp-buildpackage
 - To update to a new sub-project you need to change the subproject/*.wrap files
 - Gbp will call `meson subprojects download` as part of the build process,
   ensuring that all the subprojects are matching the wrap files expectations.

Patches to subprojects can be either applied by:
 - Explicitly picking an upstream commit as wrap file revision
 - Adding a diff file to the wrap files
 - Use another git branch or fork with only fixes applied on top

In any case the generated source package will contain the contents as it will be
built and shipped, making it easier for reviewers to understand the changes.

## Versioning system

In order to make automated GNOME shell versions checks to work and to make easier
to understand the GNOME shell version we target to we use this versioning schema:

  G . U.R . Mubuntu
  |    |    |
  |    |    +------- Micro release updates (starting from 0)
  |    +------------ Ubuntu Release version we target to (e.g. 25.10)
  +----------------- GNOME Shell release major version (e.g. 49)

So for example: 49.25.10.0ubuntu

## Track runtime dependencies

To help tracking runtime dependencies, debian/gjs-check-runtime-dependencies.sh
is provided, and it allows to help finding the runtime dependencies for the js
files.

Note that this tool result still requires manual review, but it can be launched
in two modes:

    # List modules dependencies and checks if they are available on system
    debian/gjs-check-runtime-dependencies.sh . check

    # Checks the dependencies and lists the packages that are providing them
    debian/gjs-check-runtime-dependencies.sh . dependencies