From e4c389bce875509a662f1191413e019da0164162 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Mon, 13 Oct 2025 18:56:05 +0200 Subject: [PATCH 01/48] Add Ubuntu Desktop workflows --- docs/contributors/patching/index.md | 1 + .../maintain-ubuntu-desktop-software.md | 1045 +++++++++++++++++ docs/contributors/setup/index.md | 2 + .../set-up-git-for-ubuntu-desktop-work.md | 458 ++++++++ 4 files changed, 1506 insertions(+) create mode 100644 docs/contributors/patching/maintain-ubuntu-desktop-software.md create mode 100644 docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md diff --git a/docs/contributors/patching/index.md b/docs/contributors/patching/index.md index ea69afcf..ff54f0cf 100644 --- a/docs/contributors/patching/index.md +++ b/docs/contributors/patching/index.md @@ -10,4 +10,5 @@ Work with Debian patches Commit changes Submit a merge proposal Dual maintenance with Salsa and git-ubuntu +maintain-ubuntu-desktop-software ``` diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md new file mode 100644 index 00000000..bea194c3 --- /dev/null +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -0,0 +1,1045 @@ +(maintain-ubuntu-desktop-software)= +# Maintain Ubuntu Desktop software + +These are some common, day-to-day operations to build, maintain and package GNOME software for Ubuntu Desktop using the Git Build Package (`gbp`) workflow. + +We'll use the `gnome-control-center` repository as an example. + +:::{note} +Some applications on Ubuntu Desktop are developed outside of Salsa and GNOME. They have their own, separate workflows, which aren't described in this guide. The Desktop Team can help you find the right instructions on Matrix: [#desktop-dev:ubuntu.com](https://app.element.io/#/room/#desktop-dev:ubuntu.com). +::: + + +## Prerequisites + +Before you start, follow the instructions in {ref}`set-up-git-for-ubuntu-desktop-work`. + + +## Team members, contributors and permissions + +If you're a community contributor and not a member of the Ubuntu Desktop Team, you have to send your contributions through a merge request: + +1. Fork the Git repository on Salsa. +1. Follow this guide and make the changes in your fork. +1. Open a Salsa merge request from your fork to the original repository. + +In some projects, no Ubuntu branch has been created in a long time. You might have to ask the Debcrafters team to create the new branch for you. You can contact them [on Matrix](https://app.element.io/#/room/#devel:ubuntu.com) or [on the Canonical Mattermost](https://chat.canonical.com/canonical/channels/debcrafters). + + +## Local changes + +With the suggested Git configuration, any non-committed changes (file modifications, additions or removal) halt the build because they won't be included. This is a safety reminder. + +What you can do when you have such changes: + +* Ignore them. The resulting package and build won't include those uncommitted changes. The `../build-area/` directory will match the last commit. + + To do this, add the `--git-ignore-new` Git option + +* Force using the current directory with your local modifications instead of the `build-area` directory, and include any local modifications to the package despite the `ignore-new` option. + + For this, use the `--git-ignore-new --git-export-dir=""` Git options. + + +## Refresh branches + +Use the following command to refresh the current `ubuntu/` branch and the corresponding `upstream/` branch. This applies only to the branches referenced in the `debian/gbp.conf` file on your current checkout. Also refresh the `pristine-tar` branch. + +* For example, on the `ubuntu/latest` branch: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp pull + + gbp:info: Fetching from default remote for each branch + gbp:info: Branch 'upstream/latest' is already up to date. + gbp:info: Branch 'ubuntu/latest' is already up to date. + gbp:info: Updating 'pristine-tar': 2bed57f20816..e59ab7422a13 + ``` + + The `pristine-tar` branch has been updated as referenced in `debian/gbp.conf`. + +* If you have a separate `ubuntu/noble` branch, with its own `upstream/46.x` branch: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git checkout ubuntu/noble + + :input: gbp pull + + gbp:info: Fetching from default remote for each branch + gbp:info: Branch 'ubuntu/noble' is already up to date. + gbp:info: Branch 'upstream/46.x' is already up to date. + gbp:info: Branch 'pristine-tar' is already up to date. + ``` + +The `gbp pull` command, contrary to `git pull`, is a way to avoid checking out each branch and pulling them one by one. With `git pull`, you need to have the branch as the current checkout for potential conflicts when pulling. + + +## Push your Git changes to Salsa + +Contrary for pulling, we are using `git push` for this action. We push all branches tracking the `origin` repository that way. We don't need to be on the correct checkout, contrary to `gbp pull`. If you follow our recommended Git configuration, the command also pushes relevant tags. + +```{terminal} +:copy: +:host: +:dir: gnome-control-center +:user: +:input: git push +``` + +:::{admonition} TODO +:class: attention +Is this it? Or do you need to specify the branch? +::: + + +(desktop-git-merge-a-new-upstream-version-to-latest)= +## Merge a new upstream version to latest + +When upstream releases a new version of a given project, you can merge the version on the `ubuntu/latest` branch. + +1. Switch to the branch where you want to import the new version, such as `ubuntu/latest`: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git fetch upstreamvcs + + :input: git checkout ubuntu/latest + ``` + +1. Create a `patch/queue/ubuntu/latest` branch that is useful in case you need to refresh patches later. + + * If you already have the `patch/queue` branch, just rebase it: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp pq rebase + ``` + + * Otherwise, create the `patch/queue` branch: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp pq import + ``` + +1. If Debian has already this upstream version, you don't have to import the actual tarball. You just merge with the latest upstream code: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git merge upstream/46.2 -m "Update upstream source from tag 'upstream/46.2'" + ``` + + The new upstream version is now merged. + +1. Only if Debian doesn't have the new version, proceed with the next steps. + + Since we don't want to have duplicated `upstream/x.y.z` tags, in this case you should push the `pristine-tar` and `upstream/` branches to `origin`. + +1. Download the tarball with the new upstream release. + +1. Import the tarball: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp import-orig ../gnome-control-center-46.2.tar.xz + + What is the upstream version? [46.2] + gbp:info: Importing '../gnome-control-center-46.2.tar.xz' to branch 'upstream/latest'... + gbp:info: Source package is gnome-control-center + gbp:info: Upstream version is 46.2 + gbp:info: Replacing upstream source on 'ubuntu/noble' + gbp:info: Successfully imported version 46.2 of ../gnome-control-center-46.2.tar.xz + ``` + + You can also use `--uscan` to let it download and import. + +1. Push all needed branches (for example, `ubuntu/latest` and `pristine-tarball` + `upstream/46.x` or `upstream/latest` if this upload is a new upstream release): + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git push + ``` + +1. Sync the affected upstream branch to Salsa, or propose it if you aren't an Ubuntu developer. Make sure to push the new tag, too. + +### Troubleshooting + +You might get the following errors when importing the tarball. + +#### Revision not found + +```{terminal} +:copy: +:host: +:dir: gnome-control-center +:user: +:input: gbp import-orig ../gnome-control-center-46.2.tar.xz + +What is the upstream version? [46.2] +gbp:info: Importing '../gnome-control-center-46.2.tar.xz' to branch 'upstream/latest'... +gbp:info: Source package is gnome-control-center +gbp:info: Upstream version is 46.2 +gbp:error: Import of ../gnome-control-center-46.2.tar.xz failed: revision '…' not found +``` + +The reason might be one of the following: + +* You didn't get the latest commits and tags in your repository metadata. Fetch them: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git fetch upstreamvcs + ``` + +* Upstream has changed the tagging pattern. Update the `debian/gbp.conf` file to match it. + +* Upstream is using an inconsistent release pattern. Therefore, the `debian/gbp.conf` file can't use a regular expression for the version. + + Find the exact tag: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git describe --tags --abbrev=0 upstreamvcs/main + ``` + + Specify the version manually: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp import-orig --upstream-vcs-tag= + ``` + +#### Upstream tag already exists + +```{terminal} +:copy: +:host: +:dir: gnome-control-center +:user: +:input: gbp import-orig ../gnome-control-center-46.2.tar.xz + +What is the upstream version? [46.2] +gbp:error: Upstream tag 'upstream/46.2' already exists +``` + +This error means that Debian already has this tarball. Merge from Debian as described earlier. + + +## Merge a new upstream version to maintenance + +When upstream releases a new version of a given project, you can merge the version on an Ubuntu maintenance branch. + +If `main` has a newer version than the maintenance branch and you are the first one to deal with that case for that maintenance release, additional steps are required. + +1. Open the `debian/gbp.conf` file. + + Check if it sets the `upstream-branch=upstream/latest` option. + +1. Check if the `ubuntu/latest` branch has a newer upstream version than the one that you are importing, which was never imported. + + For example: + + - `ubuntu/latest` is on 46.2 + - `ubuntu/noble` is on 46.1 and we want to update to 46.2 + - We have `pristine-tar` having 46.1 and 46.2 imported + - Consequently, the `upstream/latest` branch has upstream commits and tags for 46.1, 46.2 and corresponding `gbp` tags `upstream/46.1` and `upstream/46.2`. + +1. If the option is present and `ubuntu/latest` is newer, proceed with the next steps. + + Otherwise, just follow these existing sections: + + 1. {ref}`desktop-git-create-a-new-maintenance-branch`. + 1. Switch to the maintenance branch. + 1. {ref}`Merge a new upstream version `, while on the maintenance branch. + +1. Switch to the maintenance branch: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git checkout ubuntu/noble + ``` + +1. Create a new `upstream/` branch. + + You need to checkout the latest version of `upstream/latest` in your maintenance branch. In this example, it's `upstream/46.1`: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git branch upstream/46.x upstream/46.1 + ``` + +1. Update the `debian/gbp.conf` file to reference the correct upstream `gbp` branch: + + ```{code-block} ini + :caption: `debian/gbp.conf` + + upstream-branch=upstream/46.x + ``` + +1. Commit the changes: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git commit -a + ``` + +1. Does Debian already have the new version in Salsa? + + * If it does, use Debian's upstream branch tags: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git merge upstream/46.2 -m "Update upstream source from tag 'upstream/46.2'" + ``` + + * If it doesn't, use an upstream tarball: + + 1. Fetch from upstream: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git fetch upstreamvcs + ``` + + 1. Download the upstream tarball. + + 1. Import the tarball: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp import-orig ../gnome-control-center-46.2.tar.xz + ``` + + 1. Push your changes, including the new branch that you want to track: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git push + + :input: git push -u upstream/46.x + ``` + +1. Push the `upstream` and `pristine-tar` branches to Salsa. + + You can push directly to the `gnome` branch if you have the permissions. Otherwise, push to your personal fork and prepare a merge request. + + :::{admonition} TODO + :class: attention + What does this mean specifically? What are the commands? + ::: + + +## Refresh patches + +When merging with an upstream release, you might need to refresh the patches. + +:::{admonition} TODO +:class: attention +How can you tell that you need to refresh? +::: + +If your `patch/queue` branch is in sync with the previous release, you can just rebase: + +```{terminal} +:copy: +:host: +:dir: gnome-control-center +:user: +:input: gbp pq rebase +``` + +Then you can use the Git rebase tools to refresh the patches. + +For the case of using `gbp import-orig`, this is better described in the [`gbp` documentation](https://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.patches.newupstream.html). + +This might not work if you're instead merging with an `upstream/x.z.y` tag or if you didn't create the `patch/queue` branch first. + +The following steps work in both cases: + +1. Switch to the corresponding branch. + +1. If the `patch-queue` branch exists, remove it: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp pq drop + ``` + +1. Try to find the first point where the patches merge. Increase the value until you don't find the previous release commit: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp pq import --force --time-machine=30 + ``` + + :::{admonition} TODO + :class: attention + How much should you increase the value and how can you tell that you should stop? + ::: + +1. Re-apply the `debian/patches/series` file on top of the new upstream code, stopping for manual action if is needed: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp pq rebase + ``` + +1. If a patch doesn't apply cleanly, fix it: + + 1. Resolve the conflict using `git add` and `git rm`. + 1. Proceed with `git rebase --continue`. + +1. Regenerate the `debian/patches` data, ready to be committed, and switch back to your `ubuntu/` branch: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp pq export --no-patch-numbers + ``` + + :::{admonition} TODO + :class: attention + Does this command both regenerate the data and switch to the branch, or are other commands needed? + ::: + +1. Once back on the `ubuntu/latest` or `ubuntu/` branch, you need to commit the changes, too. + + :::{admonition} TODO + :class: attention + Commands? Just a regular `git add && git commit`? + ::: + + +(desktop-git-add-or-modify-patches)= +## Add or modify patches + +You can turn patch files into commits on a branch. This enables you to add new patches or modify existing ones. + +1. Switch to the correct `ubuntu/` branch or your local `experimental-feature` branch. For example: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git checkout ubuntu/latest + ``` + +1. Turn all patches from the `debian/patches/` directory into Git commits: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp pq rebase + + gbp:info: Switching to 'patch-queue/ubuntu/latest' + Current branch patch-queue/ubuntu/latest is up to date. + ``` + + This command creates the `patch-queue/ubuntu/latest` branch and switches to it. This branch is based on the `ubuntu/latest` branch, and all patches referenced in the `debian/patches/series` file are applied as separate commits on top of it. + +1. Check the commits: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git missing ubuntu/latest.. + + * 11a3a8cc6 - (HEAD -> patch-queue/ubuntu/latest) [PATCH] night-ligth-dialog: Avoid dereferencing invalid p + ointer (5 minutes ago) + * da06252e1 - [PATCH 4/4] thunderbolt: move to the 'Devices' page (5 minutes ago) + * 2c9f5bcbb - [PATCH 3/4] thunderbolt: new panel for device management (5 minutes ago) + * 660e9e633 - [PATCH 2/4] shell: Icon name helper returns symbolic name (5 minutes ago) + * a78ae89dd - [PATCH 1/4] shell: Don't set per-panel icon (5 minutes ago) + […] + ``` + + This is similar to using `git log` to browse the commits, which also works. + +1. Add or modify patches: + + * Modify the software. Fix a bug or add a new feature. This will be the content of your new patch. + + When you commit your changes, every new commit turns into a separate patch applied at the end of the `debian/patches/series` file. The commit description will be then converted to the patch description. + + If you want to build a package with the current content without having to switch your branch, use the following command: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp buildpackage --git-ignore-new --git-export-dir="" + ``` + + * Reorder your patches. If you don't want this patch to be the last one, you can use an interactive Git rebase: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git rebase -i ubuntu/latest + ``` + + There, you can reorder the patches as commits, amend or stash them. Removing a commit also removes the patch from the `debian/patches/series` file. + + * Remove or edit patches. Any change to the commits will result in the same change to the patch files. + + For example, you can use Git amend to modify the commit history. For details, see [Git Tools - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History). + +1. Reapply all your changes to the original branch: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp pq export --no-patch-numbers + + gbp:info: On 'patch-queue/ubuntu/latest', switching to 'ubuntu/latest' + gbp:info: Generating patches from git (ubuntu/latest..patch-queue/ubuntu/latest) + ``` + +1. Update the changelog. For details, see {ref}`desktop-git-update-the-changelog`. + +1. The new patches end up as unstages changes on your branch. Commit your changes. + +:::{note} +The `gbp pq` command unfuzzes a lot of patches every time you use it, creating some noise. Add those changes separated from your new or modified patch hack. + +And either push the change to your branch or to the main branches with a simple git push! +::: + +:::{admonition} TODO +:class: attention +I don't know what this note is trying to say. +::: + +### Additional resources + +For a different patching workflow using the `quilt` tool, see {ref}`how-to-work-with-debian-patches`. + + +## Cherry-pick upstream commits + +1. Refresh the upstream repository. + + We don't have a local checkout, only a remote that we need to refresh: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git fetch upstreamvcs + ``` + +1. Find the commits that you want to cherry-pick. Browse the Git history. + + For example, look at the Git log of the `main` branch: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git log -p upstreamvcs/main + ``` + + Many GNOME projects now use `main` instead of `master`. If your project is still using `master`, adjust the branch: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git log -p upstreamvcs/master + ``` + +1. Cherry-pick a commit as a patch. For example, on the `ubuntu/latest` branch: + +1. Switch to the branch where you want to add the cherry-picked commit. For example, on the `ubuntu/latest` branch: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git checkout ubuntu/latest + ``` + +1. Update the branch: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git pull + ``` + +1. Turn patches into commits: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp pq rebase + ``` + + :::{note} + Instead, you can also use the following commands. This deletes your patch queue and re-creates it from `debian/patches`, which can be useful if the `patch-queue` branch gets out of sync with `latest`: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp pq drop + + :input: gbp pq import + ``` + ::: + +1. Display the upstream Git log in the patch format: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git log -p upstream/latest + ``` + + :::{admonition} TODO + :class: attention + What is this for? It seems to just display the log without affecting your repository in any way. + ::: + +1. Cherry-pick your selected commit using its hash and edit the commit message: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git cherry-pick -e -x + ``` + +1. Are there any conflicts? + + If there are no conflicts, edit the commit message to comply with {ref}`dep-3-patch-file-headers`. This will end up as the patch header. + + If there are conflicts: + + 1. Fix them. For example: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git mergetool + ``` + + 1. Continue with cherry-picking: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git cherry-pick --continue + ``` + + 1. Edit the commit message to comply with {ref}`dep-3-patch-file-headers`. + +1. Reapply all your changes to the original branch: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp pq export --no-patch-numbers + ``` + +1. Update the changelog. For details, see {ref}`desktop-git-update-the-changelog`. + +1. Commit the changes: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git add debian/patches/* debian/changelog + + :input: git commit + ``` + +For details about `gbp pq`, see {ref}`desktop-git-add-or-modify-patches`. + + +(desktop-git-update-the-changelog)= +## Update the changelog + +You can edit the `debian/changelog` file manually but it's recommended to use the following command instead: + +```{terminal} +:copy: +:host: +:dir: gnome-control-center +:user: +:input: gbp dch +``` + +By default, this command adds the first line of every commit to the changelog. You can adjust this behavior by including a string at the end of your commit message: + +`Gbp-Dch: Full` +: Add this full commit message, not just the first line. + +`Gbp-Dch: Ignore` +: Skip this commit in the changelog. + + +## Import an Ubuntu upload tracked outside of VCS + +You can import a Debian Source Control (DSC) source package as a tarball, even if it doesn't exist in the Git version tracking system (VCS). + +:::{admonition} TODO +:class: attention +This procedure really needs a review. I rearranged the steps but I'm not sure if they still work. +::: + +1. Downloading the source tarball. + +1. Switch to the branch where you want to place this Ubuntu upload. + +1. Import the tarball: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp import-dsc ../gnome-control-center_46.1-0ubuntu5.dsc + ``` + +1. If there had been changes in your tree, importing the latest tarball reverted all previous changes in the VCS. + + To restore your changes, you could rewrite the history using a Git rebase. However, everyone who pulls from the repository would have conflicts upon refreshing. This is discouraged. + + Instead, reintroduce your changes by cherry-picking the commits. Because your commits are already in tree but reverted, you must cherry-pick using the following commands: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git show | git apply + + :input: git commit -C + ``` + +1. Push the changes: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git push + ``` + + This pushes all needed branches, such as `ubuntu/latest`, and `pristine-tarball` + `upstream/latest` if this upload is a new upstream release. + + +(desktop-git-create-a-new-maintenance-branch)= +## Create a new maintenance branch + +1. Find the latest version in common between the development release and that maintenance branch. + + Here, we'll use the `ubuntu/1%46.1-0ubuntu4` version tag as an example. + +2. Create a branch from the start starting point. + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git branch ubuntu/noble ubuntu/1%46.1-0ubuntu4 + + :input: git checkout ubuntu/noble + ``` + +3. In the `debian/gbp.conf` file, change `debian-branch` to `ubuntu/noble`: + + ```{code-block} ini + :caption: `debian/gbp.conf` + + debian-branch = ubuntu/noble + ``` + +4. In the `debian/control` file, change `Vcs-Browser` to the branch's page on `https://salsa.debian.org//tree/`. For example: + + ```{code-block} ini + :caption: `debian/control` + + Vcs-Browser: https://salsa.debian.org/gnome-team/gnome-control-center/tree/ubuntu/noble + ``` + + :::{admonition} TODO + :class: attention + Should this really be `debian/control`, which says that it's auto-generated and you shouldn't edit it? Should you edit `debian/control.in` instead? + ::: + +5. At the end of the `Vcs-Git` value, use the `-b ubuntu/noble` option. For example: + + ```{code-block} ini + :caption: `debian/control` + + Vcs-Git: https://salsa.debian.org/gnome-team/gnome-control-center.git -b ubuntu/noble + ``` + +6. Preserve the Debian `Vcs-*` values as `XS-Debian-Vcs-*`. + + :::{admonition} TODO + :class: attention + So what should you do here? Both `Vcs-*` and `XS-Debian-Vcs-*` options already exist in the file. Should you edit anything? + ::: + +7. Commit the changes: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git commit -a + ``` + +4. Push your changes to Salsa and track that branch: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git push -u origin ubuntu/noble + + Total 0 (delta 0), reused 0 (delta 0) + To git+ssh://git@salsa.debian.org:gnome-team/gnome-control-center + * [new branch] ubuntu/noble -> ubuntu/noble + Branch 'ubuntu/noble' set up to track remote branch 'ubuntu/noble' from 'origin'. + ``` + + +## Merge with Debian + +Do not forget to include up to the Debian version as a -v argument to dpkg-genchanges, so that it appears in the changes file too and is display. + +TO BE CONTINUED + +:::{admonition} TODO +:class: attention +We'll work on this with Nathan. It belongs under `dput` commands. +::: + + +## Build a package locally + +* Build a binary package: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp buildpackage + ``` + +* Build a source package: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp buildpackage -S + ``` + +With the proposed configuration, the artifacts all end up in the `../build-area` directory, including the tarball, which is reconstructed from the `pristine-tar` + `upstream/latest` branch. The build directory is then cleaned up. + +Useful tips in some potential cases: + +* Don't purge the `build-area` directory after building: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp buildpackage --git-no-purge + ``` + +* Build current branch with local uncommitted modifications: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp buildpackage --git-ignore-new --git-export-dir="" + ``` + + +## Release a new version + +:::{note} +If this is a sponsored upload, the sponsor performs these steps. +::: + +1. Generate the changelog for native packages. For details, see {ref}`desktop-git-update-the-changelog`. + +1. You might need to manually edit the `debian/changelog` file to properly group changes per people. + +1. Finalize the changelog. On the corresponding branch: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: dch -r "" + + :input: git commit debian/changelog -m "Finalize changelog" + ``` + +1. Build the binary and source package: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp buildpackage --git-tag-only + + :input: gbp buildpackage -S + ``` + +1. Upload the files to the Debian package upload queue: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: dput ../build-area/….changes + ``` + + :::{admonition} TODO + :class: attention + What's `../build-area/….changes`? Looks like a rendering artifact. + ::: + +1. Push the changes to Salsa: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git push + ``` + +1. Push the tags that we care about to Salsa: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git tag | grep -E '^ubuntu/|^debian/|^upstream/' | xargs -r git push + ``` + + This pushes all tracked branches to Salsa if you made any changes. The branches include: + + * `ubuntu/latest` + * `ubuntu/old-series` + * `pristine-tar` + * `upstream/lastest` diff --git a/docs/contributors/setup/index.md b/docs/contributors/setup/index.md index 06ac6f5a..e11a0cb1 100644 --- a/docs/contributors/setup/index.md +++ b/docs/contributors/setup/index.md @@ -7,3 +7,5 @@ Set up for Ubuntu development Get the source of a package Consider PGP key storage recommendations +set-up-git-for-ubuntu-desktop-work +``` diff --git a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md new file mode 100644 index 00000000..38a853c6 --- /dev/null +++ b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md @@ -0,0 +1,458 @@ +(set-up-git-for-ubuntu-desktop-work)= +# Set up Git for Ubuntu Desktop work + +The [Desktop Team](https://library.canonical.com/our-organisation/ubuntu-engineering/desktop) uses Git and Git Build Package (`gbp`) to maintain GNOME packages for Ubuntu. Let's set up your system so that you can contribute to GNOME on Ubuntu Desktop. + +We'll use the Settings application as an example. Internally, the application is known as the GNOME Control Center. + + +## Initial setup + +1. Install the basic packages for working in Git: + + ```{terminal} + :copy: + :host: + :dir: + :user: + :input: sudo apt install git git-buildpackage + ``` + +2. Install Ubuntu packaging tools: + + ```{terminal} + :copy: + :host: + :dir: + :user: + :input: sudo apt install gnupg pbuilder ubuntu-dev-tools apt-file + ``` + + For details about the packaging environment, see [Getting Set Up](https://canonical-ubuntu-packaging-guide.readthedocs-hosted.com/en/1.0/tutorial/getting-set-up.html) in the Ubuntu Packaging Guide. + +3. In the Software & Updates application, enable {guilabel}`Source code` on the {guilabel}`Ubuntu Software` tab. + + This provides information about the source repository of every package so that you can easily clone it. + +4. Enable the `salsa:name-or-team/repo` and `salsa-gnome:repo` short format for Salsa Git repositories. + + Add the following configuration to your `~/.config/git/config` file: + + ```{code-block} ini + :caption: `~/.config/git/config` + + [url "git@salsa.debian.org:"] + insteadof = salsa: + + [url "git@salsa.debian.org:gnome-team/"] + insteadof = salsa-gnome: + ``` + +5. Automatically sign tags with your GPG key. + + Add the following configuration to your `~/.gbp.conf` file: + + ```{code-block} ini + :caption: `~/.gbp.conf` + + [buildpackage] + sign-tags = True + keyid = 0xGPGKEYID + ``` + + Replace `GPGKEYID` with your GPG key ID, which is the last eight digits of your public GPG key. + + +## Optional configuration + +The following configuration can simplify certain tasks on Ubuntu Desktop projects. + +Enable Git command aliases: + +```{code-block} ini +:caption: `~/.config/git/config` + +[alias] + matching-tags = "!f() { git for-each-ref --sort=creatordate --format '%(refname)' refs/tags| grep \"$1\"| sed s,^refs/tags/,,; }; f" + last-tags = matching-tags '.*' + last-match-tag = "!f() { git matching-tags $1 | tail -n1; }; f" + last-tag = last-match-tag '.*' + last-debian-tag = last-match-tag debian/ + last-ubuntu-tag = last-match-tag ubuntu/ + ubuntu-delta = "!f() { git diff $(git last-debian-tag) -- ${1:-debian} ':(exclude)debian/changelog'; }; f" +``` + +Export the `../build-area/` directory before building with the `git-buildpackage` tool: + +```{code-block} ini +:caption: `~/.gbp.conf` + +[buildpackage] +export-dir = ../build-area/ +``` + +For details, see the `gbp.conf(5)` and `gbp-buildpackage` man pages. + + +## Required accounts + +1. If you don't have accounts on the following GitLab instances, create them: + + * [GNOME GitLab](https://gitlab.gnome.org/) is the upstream GNOME repository. + * [Salsa](https://salsa.debian.org/) hosts the Debian and Ubuntu packaging and modifications. + + It might take a while for your account to be approved. + +2. In your account preferences, upload your SSH public key to be able to interact with the Git repositories. + + +## Clone a repository + +Let's clone the GNOME Control Center repository. + +1. Check if the package provides information about its source repository: + + ```{terminal} + :copy: + :host: + :dir: + :user: + :input: apt-cache showsrc gnome-control-center | grep Vcs + + Vcs-Browser: https://salsa.debian.org/gnome-team/gnome-control-center/tree/ubuntu/master + Vcs-Git: https://salsa.debian.org/gnome-team/gnome-control-center.git -b ubuntu/master + Debian-Vcs-Browser: https://salsa.debian.org/gnome-team/gnome-control-center + Debian-Vcs-Git: https://salsa.debian.org/gnome-team/gnome-control-center.git + ``` + + A link to a Git repository is attached to this package. We can clone it using the `debcheckout` tool. + +2. Clone the repository from the Salsa remote: + + ```{terminal} + :copy: + :host: + :dir: + :user: + :input: debcheckout --git-track=* gnome-control-center + + declared git repository at https://salsa.debian.org/gnome-team/gnome-control-center/ + git clone https://salsa.debian.org/gnome-team/gnome-control-center -b ubuntu/latest gnome-control-center ... + […] + ``` + + If the `Vcs-Git` field was missing or incorrect, you could clone the repository manually using `gbp`: + + ```{terminal} + :copy: + :host: + :dir: + :user: + :input: gbp clone salsa-gnome:gnome-control-center + + gbp:info: Cloning from 'salsa-gnome:gnome-control-center' + ``` + + +## Configure branches + +1. Switch to the cloned repository: + + ```{terminal} + :copy: + :host: + :dir: + :user: + :input: cd gnome-control-center + ``` + +1. Enable Git to push tags automatically because `gbp` relies on them. + + Apply this as local configuration in the cloned repository: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git config push.followTags true + ``` + +1. Add the upstream GNOME remote repository and call it `upstreamvcs`: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git remote add -f upstreamvcs git@ssh.gitlab.gnome.org:GNOME/gnome-control-center.git + ``` + +1. Check that you now have the following three branches: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git branch -vv + + pristine-tar a96c0e2e98 [origin/pristine-tar] pristine-tar data for gnome-control-center_49.0.orig.tar.xz + * ubuntu/latest a8640ab8a4 [origin/ubuntu/latest] debian/salsa-ci: Enable for ubuntu + upstream/latest 4db8b3a502 [origin/upstream/latest] New upstream version 49.0 + ``` + +1. Check that you have the following two remotes: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git remote + + origin + upstreamvcs + ``` + + +## Examine the branches and repositories + +We use a layout with two remote repositories. Let's take a look. + +Run these commands in the `gnome-control-center` repository that we cloned earlier. + +```{terminal} +:copy: +:host: +:dir: gnome-control-center +:user: +:input: git remote show +``` + +The command lists the following remote repositories: + +`origin` +: Points to the Salsa repository. The default for pull and push without any argument. + +`upstreamvcs` +: Points to the upstream GNOME repository, to easily cherry-pick upstream fixes. + + This remote is called `upstreamvcs` to not be confused with local branch names, which might be called `debian/branchname` or `upstream/branchname`. Instead of having a local `debian/latest` branch tracking the `debian/debian/latest` remote, we have the `debian/latest` local branch tracking the `origin/debian/latest` remote, which is easier to understand. + +:::{note} +The `debian/latest` and `ubuntu/latest` branches were previously called `debian/master` and `ubuntu/master`, respectively. We renamed them on 4 September 2023 to use more inclusive naming and more closely follow [DEP-14](https://dep-team.pages.debian.net/deps/dep14/). +::: + +These names of remote repositories are local to your system. You can rename them without affecting the content of the remote repositories. + +### Salsa remote branches + +Let's look at the various branches in the Salsa remote repository: + +```{terminal} +:copy: +:host: +:dir: gnome-control-center +:user: +:input: git remote show origin + +* remote origin + […] + HEAD branch: debian/latest + Remote branches: + pristine-tar tracked + ubuntu/latest tracked + upstream/latest tracked + […] +``` + +`ubuntu/latest` +: This branch is the content of the latest Ubuntu development release. Work ready to be uploaded or uploaded in a development release mostly happens here. It's the default branch. + +`pristine-tar` +: This branch is an internal `gbp-buildpackage` branch, used to reconstruct release tarballs using `upstream/latest`. You don't interact with it directly. + +`upstream/latest` +: This is another internal `gbp-buildpackage` branch. It's a merge between the upstream Git branch corresponding to the latest release from the upstream repository and extra content coming from the tarball. You don't interact with it directly. + +We find back those 3 branches locally: + +```{terminal} +:copy: +:host: +:dir: gnome-control-center +:user: +:input: git branch +``` + +`ubuntu/latest` +: Pull and push from the `origin` (Salsa) remote repository, tracking the `ubuntu/latest` remote branch (`origin/ubuntu/latest`). + +`pristine-tar` +: Pull and push from the `origin` (Salsa) remote repository, tracking the `pristine-tar` remote branch (`origin/pristine-tar`). + +`upstream/latest` +: Pull from the `upstream` remote repository, tracking the `latest` remote branch (`upstream/latest`), and push to the `origin` (Salsa) remote repository, tracking the `upstream/latest` remote branch (`origin/upstream/latest`). + +In this configuration, you only interact with the `ubuntu/latest` branch and let `gbp` handle the other two branches. When you pull and push using `gbp`, it keeps all three branches up to date if no conflict occurs. This is easier than checking out every branch before pushing them. + +### Maintenance branches + +Many release maintenance branches are available on the Salsa remote repository: + +```{terminal} +:copy: +:host: +:dir: gnome-control-center +:user: +:input: git remote show origin + +* remote origin + […] + Remote branches: + […] + pristine-tar tracked + ubuntu/noble tracked + ubuntu/latest tracked + upstream/latest tracked + upstream/46.x tracked + […] +``` + +`ubuntu/noble` +: This branch contains the version of the project for the given Ubuntu release. In this example, the branch contains GNOME Control Center 46 for Ubuntu Noble. When a new release comes out of development, its `ubuntu/latest` branch becomes a maintenance branch. + +`upstream/46.x` +: This is a maintenance branch tracking a particular upstream GNOME series, similar to the `ubuntu/noble` branch. It's derived from the `upstream/latest` branch when a new upstream release comes out. + + This branch is only necessary if you imported a new tarball (like the 46 series) in `upstream/latest` and you want to release a yet unimported 46.3 upstream release in Noble, for instance. + + This branch is automatically managed by `gbp buildpackage`. + +Each remote branch should have a corresponding local branch when working on Noble. + +Let's track the `ubuntu/noble` maintenance branch: + +```{terminal} +:copy: +:host: +:dir: gnome-control-center +:user: +:input: git checkout ubuntu/noble + +Switched to branch 'ubuntu/noble' +Your branch is up to date with 'origin/ubuntu/noble'. +``` + +:::{note} +This short syntax is only available because we created a local `ubuntu/noble` branch that tracks the matching `ubuntu/noble` branch on the `origin` repository. + +To create another local branch that tracks a remote branch, use the following commands: + +```{terminal} +:copy: +:host: +:dir: gnome-control-center +:user: +:input: git branch -u / + +:input: git checkout +``` +::: + + +### Debian remote branches + +In addition, we have at least one other branch tracking the Salsa Debian remote repository. Their main (default) branch is called `debian/latest`: + +`debian/latest` +: Pull from the `origin` remote repository, tracking the `debian/latest` remote branch. You can only push if you're are a Debian developer. + +### Upstream GNOME remote branches + +By default, we don't have upstream GNOME branches checked out locally. We added the `upstreamvcs` repository and have access to its content, which will be fetched when importing a new upstream tarball thanks to the version tag, and inject the history in `upstream/latest` (or `upstream/version`, as explained before). + +:::{admonition} TODO +:class: attention +That's a long sentence. Who fetches the content? Who injects the history? What does it mean to inject history in Git? +::: + +Let's browse the content of the `upstreamvcs` repository: + +```{terminal} +:copy: +:host: +:dir: gnome-control-center +:user: +:input: git remote show upstreamvcs + +* remote upstreamvcs +[…] + HEAD branch: main + Remote branches: +[…] + gnome-49 tracked +[…] +``` + +You can check out any of those branch locally. We have the local `upstream/latest` branch tracking the `main` branch of the `upstreamvcs` repository. We can track any additional branches as needed for cherry-picking fixes. + +:::{admonition} TODO +:class: attention +That's not true though. `upstream/latest` is tracking `origin/upstream/latest` in my testing. +::: + +Let's check out the `upstreamvcs/main` branch locally and call it `upstreamvcs-main`: + +```{terminal} +:copy: +:host: +:dir: gnome-control-center +:user: +:input: git checkout -b upstreamvcs-main upstreamvcs/main + +Branch 'upstreamvcs-main' set up to track remote branch 'main' from 'upstreamvcs'. +Switched to a new branch 'upstreamvcs-main' +``` + +### Summary + +To sum up all this, our minimal setup consists of the following local branches. Their remote tracking branches are in square brackets (`[]`): + +```{terminal} +:copy: +:host: +:dir: gnome-control-center +:user: +:input: git branch -vv + + debian/latest 1f06aced56 [origin/debian/latest] debian/salsa-ci: Enable for debian + upstreamvcs-main b3b4035c07 [upstreamvcs/main] Update Brazilian Portuguese translation + pristine-tar a96c0e2e98 [origin/pristine-tar] pristine-tar data for gnome-control-center_49.0.orig.tar.xz +* ubuntu/latest a8640ab8a4 [origin/ubuntu/latest] debian/salsa-ci: Enable for ubuntu + upstream/latest 4db8b3a502 [origin/upstream/latest] New upstream version 49.0 +``` + +In addition, we can have several other branches: + +* An Ubuntu maintenance branch, such as for Ubuntu Noble +* A `gbp buildpackage` tarball branch linked to the maintenance release, such as for GNOME 46 +* An upstream `main` branch checked out as a local branch + +```{terminal} +:copy: +:host: +:dir: gnome-control-center +:user: +:input: git branch -vv + ubuntu/noble 10ee426e74 [origin/ubuntu/noble] Upload to noble + upstream/46.x f5817b6dce [origin/upstream/46.x] New upstream version 46.7 + upstreamvcs-main b3b4035c07 [upstreamvcs/main] Update Brazilian Portuguese translation +``` + + +## Next steps + +Now that your Git setup is complete, you can contribute to Ubuntu Desktop software. You can build, modify, maintain and package applications. See {ref}`maintain-ubuntu-desktop-software`. + From fe248a32a5f45d184e9adc0bcdd7cee01f20eadc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Wed, 15 Oct 2025 11:55:08 +0200 Subject: [PATCH 02/48] Explain the short GPG key --- .../set-up-git-for-ubuntu-desktop-work.md | 23 +++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md index 38a853c6..1ddebf90 100644 --- a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md +++ b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md @@ -48,7 +48,26 @@ We'll use the Settings application as an example. Internally, the application is insteadof = salsa-gnome: ``` -5. Automatically sign tags with your GPG key. +5. Some projects might require that you sign tags with your GPG key. Enable automatic signing. + + Display your public GPG key: + + ```{terminal} + :copy: + :host: + :dir: + :user: + :input: gpg --list-secret-keys --fingerprint + + /home/user/.gnupg/pubring.kbx + ----------------------------------------------------- + sec rsa2048 YYYY-MM-DD [SC] + XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX D1B7 6B89 + uid [ unknown] Key Name + ssb rsa2048 YYYY-MM-DDD [E] + ``` + + Your short GPG key ID is the last eight digits of your public GPG key, or `D1B76B89` in this example. Add the following configuration to your `~/.gbp.conf` file: @@ -60,7 +79,7 @@ We'll use the Settings application as an example. Internally, the application is keyid = 0xGPGKEYID ``` - Replace `GPGKEYID` with your GPG key ID, which is the last eight digits of your public GPG key. + Replace `GPGKEYID` with your short GPG key ID. ## Optional configuration From 0094543c04d00b6deb89e8901332135009c9c082 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Wed, 15 Oct 2025 12:01:58 +0200 Subject: [PATCH 03/48] latest can also be called main or master --- .../patching/maintain-ubuntu-desktop-software.md | 4 ++++ .../setup/set-up-git-for-ubuntu-desktop-work.md | 6 +++++- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index bea194c3..a250fcab 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -1,3 +1,7 @@ +--- +relatedlinks: "[PackagingWithGit - Debian Wiki](https://wiki.debian.org/PackagingWithGit)" +--- + (maintain-ubuntu-desktop-software)= # Maintain Ubuntu Desktop software diff --git a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md index 1ddebf90..3740eb5a 100644 --- a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md +++ b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md @@ -1,3 +1,7 @@ +--- +relatedlinks: "[PackagingWithGit - Debian Wiki](https://wiki.debian.org/PackagingWithGit)" +--- + (set-up-git-for-ubuntu-desktop-work)= # Set up Git for Ubuntu Desktop work @@ -286,7 +290,7 @@ Let's look at the various branches in the Salsa remote repository: […] ``` -`ubuntu/latest` +`ubuntu/latest`, sometimes `ubuntu/main` or `ubuntu/master` : This branch is the content of the latest Ubuntu development release. Work ready to be uploaded or uploaded in a development release mostly happens here. It's the default branch. `pristine-tar` From 7312f405064d4949a4504cec711b466ccb1c1eb8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Wed, 15 Oct 2025 12:59:34 +0200 Subject: [PATCH 04/48] Clarify upstreamvcs branches --- .../setup/set-up-git-for-ubuntu-desktop-work.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md index 3740eb5a..0eb294a2 100644 --- a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md +++ b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md @@ -394,11 +394,10 @@ In addition, we have at least one other branch tracking the Salsa Debian remote ### Upstream GNOME remote branches -By default, we don't have upstream GNOME branches checked out locally. We added the `upstreamvcs` repository and have access to its content, which will be fetched when importing a new upstream tarball thanks to the version tag, and inject the history in `upstream/latest` (or `upstream/version`, as explained before). +By default, we don't have upstream GNOME branches checked out locally. We added the `upstreamvcs` repository and have access to its content. -:::{admonition} TODO -:class: attention -That's a long sentence. Who fetches the content? Who injects the history? What does it mean to inject history in Git? +:::{note} +Later, we'll import a new upstream tarball, representing a new release of the `gnome-control-center` project. The `gbp` tool will fetch the content of `upstreamvcs` thanks to the version tag. ::: Let's browse the content of the `upstreamvcs` repository: @@ -419,14 +418,11 @@ Let's browse the content of the `upstreamvcs` repository: […] ``` -You can check out any of those branch locally. We have the local `upstream/latest` branch tracking the `main` branch of the `upstreamvcs` repository. We can track any additional branches as needed for cherry-picking fixes. +The branches within `origin/upstream` on Salsa, such as the `origin/upstream/latest` branch, tag unmodified releases from the GNOME `upstreamvcs` remote, without the Debian packaging and changes. As a result, the local `upstream/latest` branch tracks the `main` branch of the `upstreamvcs` repository. -:::{admonition} TODO -:class: attention -That's not true though. `upstream/latest` is tracking `origin/upstream/latest` in my testing. -::: +You can check out any of those branch locally. We can track any additional branches as needed for cherry-picking fixes. -Let's check out the `upstreamvcs/main` branch locally and call it `upstreamvcs-main`: +Our convention is to check out the `upstreamvcs/main` branch locally and call it `upstreamvcs-main`: ```{terminal} :copy: From 5c289a8b214141bed3b2c7bdb77202cc7d96e9cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Wed, 15 Oct 2025 13:02:26 +0200 Subject: [PATCH 05/48] Unnecessary words --- docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md index 0eb294a2..22035c0c 100644 --- a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md +++ b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md @@ -437,7 +437,7 @@ Switched to a new branch 'upstreamvcs-main' ### Summary -To sum up all this, our minimal setup consists of the following local branches. Their remote tracking branches are in square brackets (`[]`): +Our minimal setup consists of the following local branches. Their remote tracking branches are in square brackets (`[]`): ```{terminal} :copy: From 3945677355b127a130f60c539fc4393a119a4a27 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Wed, 15 Oct 2025 13:23:14 +0200 Subject: [PATCH 06/48] How to reset local changes --- .../maintain-ubuntu-desktop-software.md | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index a250fcab..c986de29 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -44,6 +44,29 @@ What you can do when you have such changes: For this, use the `--git-ignore-new --git-export-dir=""` Git options. +* Remove the local changes: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: dh_clean + ``` + + If that command doesn't work for you package, you can reset the changes in the following way: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git checkout . + + :input: git clean -fd . + :input: quilt -f pop -a + ``` + ## Refresh branches From 7a00551feb28f87b93c7bd976225276455eeb153 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Wed, 15 Oct 2025 13:27:15 +0200 Subject: [PATCH 07/48] Clarify pushing to Salsa --- .../patching/maintain-ubuntu-desktop-software.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index c986de29..095267da 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -111,7 +111,7 @@ The `gbp pull` command, contrary to `git pull`, is a way to avoid checking out e ## Push your Git changes to Salsa -Contrary for pulling, we are using `git push` for this action. We push all branches tracking the `origin` repository that way. We don't need to be on the correct checkout, contrary to `gbp pull`. If you follow our recommended Git configuration, the command also pushes relevant tags. +To contribute changes back to Salsa, push your changes using Git. For example: ```{terminal} :copy: @@ -121,11 +121,6 @@ Contrary for pulling, we are using `git push` for this action. We push all branc :input: git push ``` -:::{admonition} TODO -:class: attention -Is this it? Or do you need to specify the branch? -::: - (desktop-git-merge-a-new-upstream-version-to-latest)= ## Merge a new upstream version to latest From 3003d0c147e41e17852d70faf86baa08d604d847 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Wed, 15 Oct 2025 14:50:11 +0200 Subject: [PATCH 08/48] Fix a typo --- docs/contributors/patching/maintain-ubuntu-desktop-software.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index 095267da..77e7b08b 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -596,7 +596,7 @@ You can turn patch files into commits on a branch. This enables you to add new p 1. Update the changelog. For details, see {ref}`desktop-git-update-the-changelog`. -1. The new patches end up as unstages changes on your branch. Commit your changes. +1. The new patches end up as unstaged changes on your branch. Commit your changes. :::{note} The `gbp pq` command unfuzzes a lot of patches every time you use it, creating some noise. Add those changes separated from your new or modified patch hack. From fd2f29e23dbfebd28607b49aa97f9a440a746be0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Wed, 15 Oct 2025 15:25:11 +0200 Subject: [PATCH 09/48] Add unstaged to the dictionary --- docs/.custom_wordlist.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 36c08b37..1af57ced 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -81,6 +81,7 @@ unapplied unapply unpatched unshareable +unstaged update_excuses uploader uploaders From 8331764935f8d4305d953d211dc886cfc0ae11be Mon Sep 17 00:00:00 2001 From: Nathan Pratta Teodosio Date: Thu, 16 Oct 2025 10:16:12 +0200 Subject: [PATCH 10/48] Clarify dpkg-genchanges -v. --- .../maintain-ubuntu-desktop-software.md | 25 ++++++++++--------- 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index 77e7b08b..8443ed25 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -931,18 +931,6 @@ This procedure really needs a review. I rearranged the steps but I'm not sure if ``` -## Merge with Debian - -Do not forget to include up to the Debian version as a -v argument to dpkg-genchanges, so that it appears in the changes file too and is display. - -TO BE CONTINUED - -:::{admonition} TODO -:class: attention -We'll work on this with Nathan. It belongs under `dput` commands. -::: - - ## Build a package locally * Build a binary package: @@ -989,6 +977,19 @@ Useful tips in some potential cases: :input: gbp buildpackage --git-ignore-new --git-export-dir="" ``` +* Use `-v` so that `dpkg-genchanges` includes all versions greater than X in the changes file: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp buildpackage -S -vX + ``` + + A typical use case for this is when merging with Debain, to include both the Ubuntu as also + the Debian part of the changelog in the changes file. See + [an example](https://launchpadlibrarian.net/820313141/gnome-control-center_49.0-1ubuntu2_source.changes). ## Release a new version From 4166717a5238a99db413c7de35302bb2732e70ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Thu, 16 Oct 2025 13:12:10 +0200 Subject: [PATCH 11/48] Front-load the use case --- .../patching/maintain-ubuntu-desktop-software.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index 8443ed25..bf2853a4 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -977,7 +977,9 @@ Useful tips in some potential cases: :input: gbp buildpackage --git-ignore-new --git-export-dir="" ``` -* Use `-v` so that `dpkg-genchanges` includes all versions greater than X in the changes file: +* When merging with Debian, include both the Ubuntu and Debian part of the changelog in the `.changes` file, which is generated by `dpkg-genchanges`. + + Add the `-vX` option to include all Debian and Ubuntu versions greater than `X`: ```{terminal} :copy: @@ -987,9 +989,8 @@ Useful tips in some potential cases: :input: gbp buildpackage -S -vX ``` - A typical use case for this is when merging with Debain, to include both the Ubuntu as also - the Debian part of the changelog in the changes file. See - [an example](https://launchpadlibrarian.net/820313141/gnome-control-center_49.0-1ubuntu2_source.changes). + For example, see the [`gnome-control-center_49.0-1ubuntu2_source.changes`](https://launchpadlibrarian.net/820313141/gnome-control-center_49.0-1ubuntu2_source.changes) generated file. + ## Release a new version From 60a4c6771cf187b75d6b0cb791fd6b5d3441da50 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Thu, 16 Oct 2025 13:22:45 +0200 Subject: [PATCH 12/48] Clarify a step --- .../patching/maintain-ubuntu-desktop-software.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index bf2853a4..c57f5106 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -898,12 +898,12 @@ This procedure really needs a review. I rearranged the steps but I'm not sure if Vcs-Git: https://salsa.debian.org/gnome-team/gnome-control-center.git -b ubuntu/noble ``` -6. Preserve the Debian `Vcs-*` values as `XS-Debian-Vcs-*`. +6. Make sure that the `XS-Debian-Vcs-Git` and `XS-Debian-Vcs-Browser` fields are set to the `Vcs-*` values but without their Ubuntu versions: - :::{admonition} TODO - :class: attention - So what should you do here? Both `Vcs-*` and `XS-Debian-Vcs-*` options already exist in the file. Should you edit anything? - ::: + ```{code-block} ini + XS-Debian-Vcs-Git: https://salsa.debian.org/gnome-team/gnome-control-center.git + XS-Debian-Vcs-Browser: https://salsa.debian.org/gnome-team/gnome-control-center + ``` 7. Commit the changes: @@ -915,7 +915,7 @@ This procedure really needs a review. I rearranged the steps but I'm not sure if :input: git commit -a ``` -4. Push your changes to Salsa and track that branch: +8. Push your changes to Salsa and track that branch: ```{terminal} :copy: From 2daad3c7c99f6760fdd85ae286a66ec303aa333e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Thu, 16 Oct 2025 13:26:46 +0200 Subject: [PATCH 13/48] Apply feedback --- .../patching/maintain-ubuntu-desktop-software.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index c57f5106..1c21c0e8 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -885,11 +885,6 @@ This procedure really needs a review. I rearranged the steps but I'm not sure if Vcs-Browser: https://salsa.debian.org/gnome-team/gnome-control-center/tree/ubuntu/noble ``` - :::{admonition} TODO - :class: attention - Should this really be `debian/control`, which says that it's auto-generated and you shouldn't edit it? Should you edit `debian/control.in` instead? - ::: - 5. At the end of the `Vcs-Git` value, use the `-b ubuntu/noble` option. For example: ```{code-block} ini From b64aca59d7b53a7206b709b5090b8435c7e6f665 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Thu, 16 Oct 2025 13:34:53 +0200 Subject: [PATCH 14/48] Add a note about debian/control.in --- .../contributors/patching/maintain-ubuntu-desktop-software.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index 1c21c0e8..d909e933 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -885,6 +885,10 @@ This procedure really needs a review. I rearranged the steps but I'm not sure if Vcs-Browser: https://salsa.debian.org/gnome-team/gnome-control-center/tree/ubuntu/noble ``` + :::{note} + Certain outdated projects might still use the `debian/control.in` file. To generate `debian/control` from it, use the `dh_gnome` tool during the `clean` target in the `debian/rules` file. + ::: + 5. At the end of the `Vcs-Git` value, use the `-b ubuntu/noble` option. For example: ```{code-block} ini From 3a4e87e7ba045628359c72cbe3931ac689740a5b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Thu, 16 Oct 2025 19:54:17 +0200 Subject: [PATCH 15/48] Missing Git option Co-authored-by: Marco Trevisan --- docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md index 22035c0c..260b56d1 100644 --- a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md +++ b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md @@ -250,7 +250,7 @@ Run these commands in the `gnome-control-center` repository that we cloned earli :host: :dir: gnome-control-center :user: -:input: git remote show +:input: git remote show -v ``` The command lists the following remote repositories: From b9d1627291c6d37a6b44527b1d04e70aa44d07cd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Thu, 16 Oct 2025 20:00:21 +0200 Subject: [PATCH 16/48] Apply review suggestions --- .../setup/set-up-git-for-ubuntu-desktop-work.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md index 260b56d1..b14896d2 100644 --- a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md +++ b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md @@ -211,6 +211,18 @@ Let's clone the GNOME Control Center repository. :input: git remote add -f upstreamvcs git@ssh.gitlab.gnome.org:GNOME/gnome-control-center.git ``` + :::{note} + If you don't have an account on the GNOME GitLab or if your account is missing an SSH key, you can also refer to the repository using the HTTPS protocol: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git remote add -f upstreamvcs https://gitlab.gnome.org/GNOME/gnome-control-center.git + ``` + ::: + 1. Check that you now have the following three branches: ```{terminal} @@ -294,7 +306,7 @@ Let's look at the various branches in the Salsa remote repository: : This branch is the content of the latest Ubuntu development release. Work ready to be uploaded or uploaded in a development release mostly happens here. It's the default branch. `pristine-tar` -: This branch is an internal `gbp-buildpackage` branch, used to reconstruct release tarballs using `upstream/latest`. You don't interact with it directly. +: This branch is an internal `gbp-buildpackage` branch, used to reconstruct release tarballs using `upstream/latest`. Usually, you don't interact with it directly. When you do need to interact with it, such as to manage the tarballs, use the `pristine-tar` tool. `upstream/latest` : This is another internal `gbp-buildpackage` branch. It's a merge between the upstream Git branch corresponding to the latest release from the upstream repository and extra content coming from the tarball. You don't interact with it directly. @@ -347,7 +359,7 @@ Many release maintenance branches are available on the Salsa remote repository: : This branch contains the version of the project for the given Ubuntu release. In this example, the branch contains GNOME Control Center 46 for Ubuntu Noble. When a new release comes out of development, its `ubuntu/latest` branch becomes a maintenance branch. `upstream/46.x` -: This is a maintenance branch tracking a particular upstream GNOME series, similar to the `ubuntu/noble` branch. It's derived from the `upstream/latest` branch when a new upstream release comes out. +: This is a maintenance branch tracking a particular upstream GNOME series, similar to the `ubuntu/noble` branch. It's derived from the `upstream/latest` branch when a new upstream release series, such as GNOME 46, comes out. This branch is only necessary if you imported a new tarball (like the 46 series) in `upstream/latest` and you want to release a yet unimported 46.3 upstream release in Noble, for instance. From ead03f4345911a4f5e072c71e3bd748dd946d2cd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Thu, 16 Oct 2025 20:19:58 +0200 Subject: [PATCH 17/48] Apply review suggestions --- .../patching/maintain-ubuntu-desktop-software.md | 10 +++++----- .../setup/set-up-git-for-ubuntu-desktop-work.md | 10 ++++++---- 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index d909e933..da444caf 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -10,7 +10,7 @@ These are some common, day-to-day operations to build, maintain and package GNOM We'll use the `gnome-control-center` repository as an example. :::{note} -Some applications on Ubuntu Desktop are developed outside of Salsa and GNOME. They have their own, separate workflows, which aren't described in this guide. The Desktop Team can help you find the right instructions on Matrix: [#desktop-dev:ubuntu.com](https://app.element.io/#/room/#desktop-dev:ubuntu.com). +Some applications on Ubuntu Desktop are developed outside of Salsa and GNOME. They have their own, separate workflows, which aren't described in this guide. The Desktop Team can help you find the right instructions on Matrix: {matrix}`desktop-dev`. ::: @@ -27,7 +27,7 @@ If you're a community contributor and not a member of the Ubuntu Desktop Team, y 1. Follow this guide and make the changes in your fork. 1. Open a Salsa merge request from your fork to the original repository. -In some projects, no Ubuntu branch has been created in a long time. You might have to ask the Debcrafters team to create the new branch for you. You can contact them [on Matrix](https://app.element.io/#/room/#devel:ubuntu.com) or [on the Canonical Mattermost](https://chat.canonical.com/canonical/channels/debcrafters). +In some projects, no Ubuntu branch has been created in a long time. You might have to ask the Desktop Team to create the new branch for you. You can contact them on Matrix at {matrix}`desktop-dev` or [on the Canonical Mattermost](https://chat.canonical.com/canonical/channels/desktop). ## Local changes @@ -932,14 +932,14 @@ This procedure really needs a review. I rearranged the steps but I'm not sure if ## Build a package locally -* Build a binary package: +* Build a binary package for your Ubuntu release and CPU architecture. For example, Ubuntu Noble on the AMD64 architecture: ```{terminal} :copy: :host: :dir: gnome-control-center :user: - :input: gbp buildpackage + :input: gbp buildpackage -b --git-builder=sbuild noble-amd64 ``` * Build a source package: @@ -949,7 +949,7 @@ This procedure really needs a review. I rearranged the steps but I'm not sure if :host: :dir: gnome-control-center :user: - :input: gbp buildpackage -S + :input: gbp buildpackage -b --git-builder=sbuild noble-amd64 -S ``` With the proposed configuration, the artifacts all end up in the `../build-area` directory, including the tarball, which is reconstructed from the `pristine-tar` + `upstream/latest` branch. The build directory is then cleaned up. diff --git a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md index b14896d2..2fcc0ff8 100644 --- a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md +++ b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md @@ -22,7 +22,7 @@ We'll use the Settings application as an example. Internally, the application is :input: sudo apt install git git-buildpackage ``` -2. Install Ubuntu packaging tools: +1. Install Ubuntu packaging tools: ```{terminal} :copy: @@ -34,11 +34,13 @@ We'll use the Settings application as an example. Internally, the application is For details about the packaging environment, see [Getting Set Up](https://canonical-ubuntu-packaging-guide.readthedocs-hosted.com/en/1.0/tutorial/getting-set-up.html) in the Ubuntu Packaging Guide. -3. In the Software & Updates application, enable {guilabel}`Source code` on the {guilabel}`Ubuntu Software` tab. +1. Install and configure the `sbuild` tool. Follow [Installing sbuild](https://canonical-ubuntu-packaging-guide.readthedocs-hosted.com/en/1.0/how-to/setting-up-sbuild.html#installing-sbuild) in the Ubuntu Packaging Guide. Set the Ubuntu releases for which you're preparing packages. + +1. In the Software & Updates application, enable {guilabel}`Source code` on the {guilabel}`Ubuntu Software` tab. This provides information about the source repository of every package so that you can easily clone it. -4. Enable the `salsa:name-or-team/repo` and `salsa-gnome:repo` short format for Salsa Git repositories. +1. Enable the `salsa:name-or-team/repo` and `salsa-gnome:repo` short format for Salsa Git repositories. Add the following configuration to your `~/.config/git/config` file: @@ -52,7 +54,7 @@ We'll use the Settings application as an example. Internally, the application is insteadof = salsa-gnome: ``` -5. Some projects might require that you sign tags with your GPG key. Enable automatic signing. +1. Some projects might require that you sign tags with your GPG key. Enable automatic signing. Display your public GPG key: From 99a08921a8cf1f212602d33956b39c18994044bf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Thu, 16 Oct 2025 20:39:03 +0200 Subject: [PATCH 18/48] Apply review suggestions --- .../maintain-ubuntu-desktop-software.md | 36 +++++++++++++++---- 1 file changed, 29 insertions(+), 7 deletions(-) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index da444caf..60933580 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -42,7 +42,7 @@ What you can do when you have such changes: * Force using the current directory with your local modifications instead of the `build-area` directory, and include any local modifications to the package despite the `ignore-new` option. - For this, use the `--git-ignore-new --git-export-dir=""` Git options. + For this, add the `--git-ignore-new --git-export=INDEX` options to `gbp`. * Remove the local changes: @@ -111,14 +111,14 @@ The `gbp pull` command, contrary to `git pull`, is a way to avoid checking out e ## Push your Git changes to Salsa -To contribute changes back to Salsa, push your changes using Git. For example: +To contribute changes back to Salsa, push your changes using `gbp`: ```{terminal} :copy: :host: :dir: gnome-control-center :user: -:input: git push +:input: gbp push ``` @@ -177,9 +177,33 @@ When upstream releases a new version of a given project, you can merge the versi Since we don't want to have duplicated `upstream/x.y.z` tags, in this case you should push the `pristine-tar` and `upstream/` branches to `origin`. -1. Download the tarball with the new upstream release. +1. Scan for new releases: -1. Import the tarball: + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: uscan + + => Newer package available from: + => https://download.gnome.org/sources/gnome-control-center/49/gnome-control-center-49.1.tar.xz + Successfully symlinked ../gnome-control-center-49.1.tar.xz to ../gnome-control-center_49.1.orig.tar.xz. + ``` + +1. Is `uscan` showing the upstream release that you want to import? + + If so, you can let `gbp` download and import the latest release automatically: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp import-origin --uscan + ``` + + Otherwise, download the tarball with the new upstream release. Then, import the tarball manually: ```{terminal} :copy: @@ -196,8 +220,6 @@ When upstream releases a new version of a given project, you can merge the versi gbp:info: Successfully imported version 46.2 of ../gnome-control-center-46.2.tar.xz ``` - You can also use `--uscan` to let it download and import. - 1. Push all needed branches (for example, `ubuntu/latest` and `pristine-tarball` + `upstream/46.x` or `upstream/latest` if this upload is a new upstream release): ```{terminal} From 85e621ac74efbdc43a8aacaf7a467cb693b20756 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Thu, 16 Oct 2025 20:39:55 +0200 Subject: [PATCH 19/48] Fix gbp options Co-authored-by: Marco Trevisan --- docs/contributors/patching/maintain-ubuntu-desktop-software.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index 60933580..ca67bbba 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -584,7 +584,7 @@ You can turn patch files into commits on a branch. This enables you to add new p :host: :dir: gnome-control-center :user: - :input: gbp buildpackage --git-ignore-new --git-export-dir="" + :input: gbp buildpackage -b --git-ignore-new --git-export=INDEX ``` * Reorder your patches. If you don't want this patch to be the last one, you can use an interactive Git rebase: From eee2e72555b1f026b1d33159bdb6285a57fc9ae7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Thu, 16 Oct 2025 20:44:55 +0200 Subject: [PATCH 20/48] Apply review suggestions --- .../patching/maintain-ubuntu-desktop-software.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index ca67bbba..fcffcfb0 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -819,6 +819,18 @@ By default, this command adds the first line of every commit to the changelog. Y `Gbp-Dch: Ignore` : Skip this commit in the changelog. +Alternatively, you can include all the commit descriptions: + +```{terminal} +:copy: +:host: +:dir: gnome-control-center +:user: +:input: gbp dch --full +``` + +Then, filter them out by hand at the commit phase. + ## Import an Ubuntu upload tracked outside of VCS From 005dab56ee51bf64f95619f84dbdf305636344ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Thu, 16 Oct 2025 20:45:38 +0200 Subject: [PATCH 21/48] Fix gbp options Co-authored-by: Marco Trevisan --- docs/contributors/patching/maintain-ubuntu-desktop-software.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index fcffcfb0..1bb6c168 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -1007,7 +1007,7 @@ Useful tips in some potential cases: :host: :dir: gnome-control-center :user: - :input: gbp buildpackage --git-ignore-new --git-export-dir="" + :input: gbp buildpackage --git-ignore-new --git-export=INDEX ``` * When merging with Debian, include both the Ubuntu and Debian part of the changelog in the `.changes` file, which is generated by `dpkg-genchanges`. From 8bcebc367335cc394dcae46e5ffefd917d29b3c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Thu, 16 Oct 2025 20:46:41 +0200 Subject: [PATCH 22/48] More precise use case Co-authored-by: Marco Trevisan --- docs/contributors/patching/maintain-ubuntu-desktop-software.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index 1bb6c168..62077391 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -1033,7 +1033,7 @@ If this is a sponsored upload, the sponsor performs these steps. 1. Generate the changelog for native packages. For details, see {ref}`desktop-git-update-the-changelog`. -1. You might need to manually edit the `debian/changelog` file to properly group changes per people. +1. You might need to manually edit the `debian/changelog` file to improve its syntax and clarity. 1. Finalize the changelog. On the corresponding branch: From 40d5b41fe166084baa342aaa4fb1748fdd22502e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Thu, 16 Oct 2025 20:57:13 +0200 Subject: [PATCH 23/48] Apply review suggestions --- .../maintain-ubuntu-desktop-software.md | 20 +++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index 62077391..2039d641 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -1035,27 +1035,35 @@ If this is a sponsored upload, the sponsor performs these steps. 1. You might need to manually edit the `debian/changelog` file to improve its syntax and clarity. -1. Finalize the changelog. On the corresponding branch: +1. Finalize the changelog and specify the Ubuntu release: ```{terminal} :copy: :host: :dir: gnome-control-center :user: - :input: dch -r "" + :input: dch -r "" --distribution noble - :input: git commit debian/changelog -m "Finalize changelog" + :input: git commit -m "Upload to Noble" debian/changelog ``` -1. Build the binary and source package: +1. Tag the package: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp buildpackage --git-tag-only --git-ignore-new + ``` + +1. Build the source package: ```{terminal} :copy: :host: :dir: gnome-control-center :user: - :input: gbp buildpackage --git-tag-only - :input: gbp buildpackage -S ``` From 3c4367b6ec8b42288992c795899ea626c2f59e2e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Thu, 16 Oct 2025 20:57:47 +0200 Subject: [PATCH 24/48] Add a file name Co-authored-by: Marco Trevisan --- docs/contributors/patching/maintain-ubuntu-desktop-software.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index 2039d641..9479e017 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -1074,7 +1074,7 @@ If this is a sponsored upload, the sponsor performs these steps. :host: :dir: gnome-control-center :user: - :input: dput ../build-area/….changes + :input: dput ../build-area/…_source.changes ``` :::{admonition} TODO From 9ee5b6d0f16c94013410c0eaff4dc60def54d346 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Thu, 16 Oct 2025 21:07:13 +0200 Subject: [PATCH 25/48] Apply review suggestions --- docs/contributors/patching/maintain-ubuntu-desktop-software.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index 2039d641..e5f36d60 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -1067,6 +1067,8 @@ If this is a sponsored upload, the sponsor performs these steps. :input: gbp buildpackage -S ``` +1. Check the `../build-area/….changes` file to make sure that it's correct. + 1. Upload the files to the Debian package upload queue: ```{terminal} From d8813931b3dbfbb4a218ca486b6a3e8967184009 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Mon, 20 Oct 2025 15:48:29 +0200 Subject: [PATCH 26/48] Apply review suggestions --- .../maintain-ubuntu-desktop-software.md | 24 +++++-------------- .../set-up-git-for-ubuntu-desktop-work.md | 2 +- 2 files changed, 7 insertions(+), 19 deletions(-) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index 678a9350..a5294bc5 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -620,17 +620,6 @@ You can turn patch files into commits on a branch. This enables you to add new p 1. The new patches end up as unstaged changes on your branch. Commit your changes. -:::{note} -The `gbp pq` command unfuzzes a lot of patches every time you use it, creating some noise. Add those changes separated from your new or modified patch hack. - -And either push the change to your branch or to the main branches with a simple git push! -::: - -:::{admonition} TODO -:class: attention -I don't know what this note is trying to say. -::: - ### Additional resources For a different patching workflow using the `quilt` tool, see {ref}`how-to-work-with-debian-patches`. @@ -966,6 +955,8 @@ This procedure really needs a review. I rearranged the steps but I'm not sure if ## Build a package locally +To build a local package, we use the `sbuild` framework and specify the target Ubuntu release. We don't recommend building the package directly on your system without using `sbuild` because the test and build phase might be affected by the state of your machine. + * Build a binary package for your Ubuntu release and CPU architecture. For example, Ubuntu Noble on the AMD64 architecture: ```{terminal} @@ -1067,7 +1058,9 @@ If this is a sponsored upload, the sponsor performs these steps. :input: gbp buildpackage -S ``` -1. Check the `../build-area/….changes` file to make sure that it's correct. +1. Check the `../build-area/.changes` file to make sure that it's correct. This file instructs `dput` which files to upload, and provides a high-level view of the changes such as the latest changelog entries. + + For example, changes to the GNU Hello program as packaged for Ubuntu would be described in the `hello_2.10-0ubuntu1.changes` file. 1. Upload the files to the Debian package upload queue: @@ -1076,14 +1069,9 @@ If this is a sponsored upload, the sponsor performs these steps. :host: :dir: gnome-control-center :user: - :input: dput ../build-area/…_source.changes + :input: dput ../build-area/.changes ``` - :::{admonition} TODO - :class: attention - What's `../build-area/….changes`? Looks like a rendering artifact. - ::: - 1. Push the changes to Salsa: ```{terminal} diff --git a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md index 2fcc0ff8..91bf78b8 100644 --- a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md +++ b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md @@ -34,7 +34,7 @@ We'll use the Settings application as an example. Internally, the application is For details about the packaging environment, see [Getting Set Up](https://canonical-ubuntu-packaging-guide.readthedocs-hosted.com/en/1.0/tutorial/getting-set-up.html) in the Ubuntu Packaging Guide. -1. Install and configure the `sbuild` tool. Follow [Installing sbuild](https://canonical-ubuntu-packaging-guide.readthedocs-hosted.com/en/1.0/how-to/setting-up-sbuild.html#installing-sbuild) in the Ubuntu Packaging Guide. Set the Ubuntu releases for which you're preparing packages. +1. Install and configure the `sbuild` tool. Follow [Installing `sbuild`](https://canonical-ubuntu-packaging-guide.readthedocs-hosted.com/en/1.0/how-to/setting-up-sbuild.html#installing-sbuild) in the Ubuntu Packaging Guide. Set the Ubuntu releases for which you're preparing packages. 1. In the Software & Updates application, enable {guilabel}`Source code` on the {guilabel}`Ubuntu Software` tab. From 707ea7d3caea8590c318f4a605c4a69866d53f8c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Mon, 20 Oct 2025 15:54:45 +0200 Subject: [PATCH 27/48] Remove unnecessary information --- .../set-up-git-for-ubuntu-desktop-work.md | 21 +------------------ 1 file changed, 1 insertion(+), 20 deletions(-) diff --git a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md index 91bf78b8..04113f84 100644 --- a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md +++ b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md @@ -275,7 +275,7 @@ The command lists the following remote repositories: `upstreamvcs` : Points to the upstream GNOME repository, to easily cherry-pick upstream fixes. - This remote is called `upstreamvcs` to not be confused with local branch names, which might be called `debian/branchname` or `upstream/branchname`. Instead of having a local `debian/latest` branch tracking the `debian/debian/latest` remote, we have the `debian/latest` local branch tracking the `origin/debian/latest` remote, which is easier to understand. + This remote is called `upstreamvcs` to not be confused with local branch names, which might be called `debian/` or `upstream/`. Instead of having a local `debian/latest` branch tracking the `debian/debian/latest` remote, we have the `debian/latest` local branch tracking the `origin/debian/latest` remote, which is easier to understand. :::{note} The `debian/latest` and `ubuntu/latest` branches were previously called `debian/master` and `ubuntu/master`, respectively. We renamed them on 4 September 2023 to use more inclusive naming and more closely follow [DEP-14](https://dep-team.pages.debian.net/deps/dep14/). @@ -313,25 +313,6 @@ Let's look at the various branches in the Salsa remote repository: `upstream/latest` : This is another internal `gbp-buildpackage` branch. It's a merge between the upstream Git branch corresponding to the latest release from the upstream repository and extra content coming from the tarball. You don't interact with it directly. -We find back those 3 branches locally: - -```{terminal} -:copy: -:host: -:dir: gnome-control-center -:user: -:input: git branch -``` - -`ubuntu/latest` -: Pull and push from the `origin` (Salsa) remote repository, tracking the `ubuntu/latest` remote branch (`origin/ubuntu/latest`). - -`pristine-tar` -: Pull and push from the `origin` (Salsa) remote repository, tracking the `pristine-tar` remote branch (`origin/pristine-tar`). - -`upstream/latest` -: Pull from the `upstream` remote repository, tracking the `latest` remote branch (`upstream/latest`), and push to the `origin` (Salsa) remote repository, tracking the `upstream/latest` remote branch (`origin/upstream/latest`). - In this configuration, you only interact with the `ubuntu/latest` branch and let `gbp` handle the other two branches. When you pull and push using `gbp`, it keeps all three branches up to date if no conflict occurs. This is easier than checking out every branch before pushing them. ### Maintenance branches From e35fe982e05d93b54572fea4b9081d5a1bbfa12f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Mon, 20 Oct 2025 17:09:15 +0200 Subject: [PATCH 28/48] Resolving TODO items --- .../maintain-ubuntu-desktop-software.md | 170 +++++++++++------- .../set-up-git-for-ubuntu-desktop-work.md | 3 +- 2 files changed, 105 insertions(+), 68 deletions(-) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index a5294bc5..f3e40e24 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -125,7 +125,7 @@ To contribute changes back to Salsa, push your changes using `gbp`: (desktop-git-merge-a-new-upstream-version-to-latest)= ## Merge a new upstream version to latest -When upstream releases a new version of a given project, you can merge the version on the `ubuntu/latest` branch. +When upstream releases a new version of a given project, you can merge the version on the Debian and Ubuntu branches. 1. Switch to the branch where you want to import the new version, such as `ubuntu/latest`: @@ -161,7 +161,21 @@ When upstream releases a new version of a given project, you can merge the versi :input: gbp pq import ``` -1. If Debian has already this upstream version, you don't have to import the actual tarball. You just merge with the latest upstream code: +1. Check whether this upstream version already exists in Debian: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git remote show origin + + […] + upstream/46.x pushes to upstream/46.x (up to date) + […] + ``` + +1. If Debian already has the upstream version, you don't have to import the tarball. Merge with the latest upstream code: ```{terminal} :copy: @@ -171,11 +185,19 @@ When upstream releases a new version of a given project, you can merge the versi :input: git merge upstream/46.2 -m "Update upstream source from tag 'upstream/46.2'" ``` - The new upstream version is now merged. + The new upstream version is now merged. Push the changes: -1. Only if Debian doesn't have the new version, proceed with the next steps. + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git push --follow-tags + ``` - Since we don't want to have duplicated `upstream/x.y.z` tags, in this case you should push the `pristine-tar` and `upstream/` branches to `origin`. +### Merge a new upstream version to Debian + +If Debian doesn't have the new upstream version, add the release to Debian and Ubuntu. 1. Scan for new releases: @@ -227,10 +249,12 @@ When upstream releases a new version of a given project, you can merge the versi :host: :dir: gnome-control-center :user: - :input: git push + :input: git push --follow-tags ``` -1. Sync the affected upstream branch to Salsa, or propose it if you aren't an Ubuntu developer. Make sure to push the new tag, too. + Since we don't want to have duplicated `upstream/x.y.z` tags, in this case you should push the `pristine-tar` and `upstream/` branches to `origin`. Make sure to push the new tag, too. + + Sync the affected upstream branch to Salsa, or propose it as a merge request if you aren't an Ubuntu developer. ### Troubleshooting @@ -320,7 +344,7 @@ If `main` has a newer version than the maintenance branch and you are the first - `ubuntu/latest` is on 46.2 - `ubuntu/noble` is on 46.1 and we want to update to 46.2 - - We have `pristine-tar` having 46.1 and 46.2 imported + - The `pristine-tar` log lists that 46.1 and 46.2 have been imported - Consequently, the `upstream/latest` branch has upstream commits and tags for 46.1, 46.2 and corresponding `gbp` tags `upstream/46.1` and `upstream/46.2`. 1. If the option is present and `ubuntu/latest` is newer, proceed with the next steps. @@ -371,72 +395,94 @@ If `main` has a newer version than the maintenance branch and you are the first :input: git commit -a ``` -1. Does Debian already have the new version in Salsa? +1. Check whether Debian already has the new version in Salsa: - * If it does, use Debian's upstream branch tags: + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git remote show origin - ```{terminal} - :copy: - :host: - :dir: gnome-control-center - :user: - :input: git merge upstream/46.2 -m "Update upstream source from tag 'upstream/46.2'" - ``` + […] + upstream/46.2 pushes to upstream/46.2 (up to date) + […] + ``` + +1. If the version already exists in Debian, use Debian's upstream branch tags: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git merge upstream/46.2 -m "Update upstream source from tag 'upstream/46.2'" + ``` + + Push the `upstream` and `pristine-tar` branches to Salsa: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git push --follow-tags + ``` - * If it doesn't, use an upstream tarball: +### Add the maintenance version in Debian - 1. Fetch from upstream: +If the version doesn't exist in Debian yet, add it to Debian and Ubuntu using an upstream tarball. - ```{terminal} - :copy: - :host: - :dir: gnome-control-center - :user: - :input: git fetch upstreamvcs - ``` +1. Fetch from upstream: - 1. Download the upstream tarball. + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git fetch upstreamvcs + ``` - 1. Import the tarball: +1. Download the upstream tarball. - ```{terminal} - :copy: - :host: - :dir: gnome-control-center - :user: - :input: gbp import-orig ../gnome-control-center-46.2.tar.xz - ``` +1. Import the tarball: - 1. Push your changes, including the new branch that you want to track: + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp import-orig ../gnome-control-center-46.2.tar.xz + ``` - ```{terminal} - :copy: - :host: - :dir: gnome-control-center - :user: - :input: git push +1. Push your changes, including the new branch that you want to track: - :input: git push -u upstream/46.x - ``` + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git push + + :input: git push -u upstream/46.x + ``` 1. Push the `upstream` and `pristine-tar` branches to Salsa. - You can push directly to the `gnome` branch if you have the permissions. Otherwise, push to your personal fork and prepare a merge request. + You can push directly to the GNOME branch if you have the permissions. Otherwise, push to your personal fork and prepare a merge request. - :::{admonition} TODO - :class: attention - What does this mean specifically? What are the commands? - ::: + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git push --follow-tags + ``` ## Refresh patches -When merging with an upstream release, you might need to refresh the patches. - -:::{admonition} TODO -:class: attention -How can you tell that you need to refresh? -::: +Before merging with an upstream release, refresh the patches. If your `patch/queue` branch is in sync with the previous release, you can just rebase: @@ -498,7 +544,7 @@ The following steps work in both cases: 1. Resolve the conflict using `git add` and `git rm`. 1. Proceed with `git rebase --continue`. -1. Regenerate the `debian/patches` data, ready to be committed, and switch back to your `ubuntu/` branch: +1. Regenerate the `debian/patches` data, ready to be committed: ```{terminal} :copy: @@ -508,17 +554,9 @@ The following steps work in both cases: :input: gbp pq export --no-patch-numbers ``` - :::{admonition} TODO - :class: attention - Does this command both regenerate the data and switch to the branch, or are other commands needed? - ::: - -1. Once back on the `ubuntu/latest` or `ubuntu/` branch, you need to commit the changes, too. +1. Switch back to your `ubuntu/latest` or `ubuntu/` branch. - :::{admonition} TODO - :class: attention - Commands? Just a regular `git add && git commit`? - ::: +1. Commit the changes. (desktop-git-add-or-modify-patches)= diff --git a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md index 04113f84..e5ef66d7 100644 --- a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md +++ b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md @@ -379,13 +379,12 @@ To create another local branch that tracks a remote branch, use the following co ``` ::: - ### Debian remote branches In addition, we have at least one other branch tracking the Salsa Debian remote repository. Their main (default) branch is called `debian/latest`: `debian/latest` -: Pull from the `origin` remote repository, tracking the `debian/latest` remote branch. You can only push if you're are a Debian developer. +: Pull from the `origin` remote repository, tracking the `debian/latest` remote branch. To push to this branch, you' must be a [Debian Developer](https://wiki.debian.org/DebianDeveloper). ### Upstream GNOME remote branches From 4b8c9bbe58fe9993f315f4572984d2608986e1af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Mon, 20 Oct 2025 17:28:09 +0200 Subject: [PATCH 29/48] Typo --- docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md index e5ef66d7..a54c5da1 100644 --- a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md +++ b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md @@ -384,7 +384,7 @@ To create another local branch that tracks a remote branch, use the following co In addition, we have at least one other branch tracking the Salsa Debian remote repository. Their main (default) branch is called `debian/latest`: `debian/latest` -: Pull from the `origin` remote repository, tracking the `debian/latest` remote branch. To push to this branch, you' must be a [Debian Developer](https://wiki.debian.org/DebianDeveloper). +: Pull from the `origin` remote repository, tracking the `debian/latest` remote branch. To push to this branch, you must be a [Debian Developer](https://wiki.debian.org/DebianDeveloper). ### Upstream GNOME remote branches From 2e5ca8c3bac3997e0bc7e2f6cc8d1c1f73e64476 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Mon, 20 Oct 2025 17:29:58 +0200 Subject: [PATCH 30/48] The branches summary was unnecessary --- .../set-up-git-for-ubuntu-desktop-work.md | 36 ------------------- 1 file changed, 36 deletions(-) diff --git a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md index a54c5da1..7e7ec88b 100644 --- a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md +++ b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md @@ -429,42 +429,6 @@ Branch 'upstreamvcs-main' set up to track remote branch 'main' from 'upstreamvcs Switched to a new branch 'upstreamvcs-main' ``` -### Summary - -Our minimal setup consists of the following local branches. Their remote tracking branches are in square brackets (`[]`): - -```{terminal} -:copy: -:host: -:dir: gnome-control-center -:user: -:input: git branch -vv - - debian/latest 1f06aced56 [origin/debian/latest] debian/salsa-ci: Enable for debian - upstreamvcs-main b3b4035c07 [upstreamvcs/main] Update Brazilian Portuguese translation - pristine-tar a96c0e2e98 [origin/pristine-tar] pristine-tar data for gnome-control-center_49.0.orig.tar.xz -* ubuntu/latest a8640ab8a4 [origin/ubuntu/latest] debian/salsa-ci: Enable for ubuntu - upstream/latest 4db8b3a502 [origin/upstream/latest] New upstream version 49.0 -``` - -In addition, we can have several other branches: - -* An Ubuntu maintenance branch, such as for Ubuntu Noble -* A `gbp buildpackage` tarball branch linked to the maintenance release, such as for GNOME 46 -* An upstream `main` branch checked out as a local branch - -```{terminal} -:copy: -:host: -:dir: gnome-control-center -:user: -:input: git branch -vv - ubuntu/noble 10ee426e74 [origin/ubuntu/noble] Upload to noble - upstream/46.x f5817b6dce [origin/upstream/46.x] New upstream version 46.7 - upstreamvcs-main b3b4035c07 [upstreamvcs/main] Update Brazilian Portuguese translation -``` - - ## Next steps Now that your Git setup is complete, you can contribute to Ubuntu Desktop software. You can build, modify, maintain and package applications. See {ref}`maintain-ubuntu-desktop-software`. From fa58d7cf109d3e8eb551cd4cee98296fc9d51574 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Fri, 24 Oct 2025 16:57:40 +0200 Subject: [PATCH 31/48] Apply review suggestions --- .../maintain-ubuntu-desktop-software.md | 42 +++++-------------- 1 file changed, 11 insertions(+), 31 deletions(-) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index f3e40e24..5224eb03 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -44,29 +44,6 @@ What you can do when you have such changes: For this, add the `--git-ignore-new --git-export=INDEX` options to `gbp`. -* Remove the local changes: - - ```{terminal} - :copy: - :host: - :dir: gnome-control-center - :user: - :input: dh_clean - ``` - - If that command doesn't work for you package, you can reset the changes in the following way: - - ```{terminal} - :copy: - :host: - :dir: gnome-control-center - :user: - :input: git checkout . - - :input: git clean -fd . - :input: quilt -f pop -a - ``` - ## Refresh branches @@ -168,11 +145,14 @@ When upstream releases a new version of a given project, you can merge the versi :host: :dir: gnome-control-center :user: - :input: git remote show origin + :input: git tag -l | grep upstream - […] - upstream/46.x pushes to upstream/46.x (up to date) - […] + […] + upstream/46.0 + upstream/46.0.1 + upstream/46.1 + upstream/46.3 + […] ``` 1. If Debian already has the upstream version, you don't have to import the tarball. Merge with the latest upstream code: @@ -182,7 +162,7 @@ When upstream releases a new version of a given project, you can merge the versi :host: :dir: gnome-control-center :user: - :input: git merge upstream/46.2 -m "Update upstream source from tag 'upstream/46.2'" + :input: git merge upstream/46.3 -m "Update upstream source from tag 'upstream/46.3'" ``` The new upstream version is now merged. Push the changes: @@ -242,7 +222,7 @@ If Debian doesn't have the new upstream version, add the release to Debian and U gbp:info: Successfully imported version 46.2 of ../gnome-control-center-46.2.tar.xz ``` -1. Push all needed branches (for example, `ubuntu/latest` and `pristine-tarball` + `upstream/46.x` or `upstream/latest` if this upload is a new upstream release): +1. Push all related branches: ```{terminal} :copy: @@ -252,9 +232,9 @@ If Debian doesn't have the new upstream version, add the release to Debian and U :input: git push --follow-tags ``` - Since we don't want to have duplicated `upstream/x.y.z` tags, in this case you should push the `pristine-tar` and `upstream/` branches to `origin`. Make sure to push the new tag, too. + The `gbp` tool handles all branches automatically. In the example of this upstream release, `gbp` pushes the `ubuntu/latest`, `pristine-tarball` + `upstream/46.x` or `upstream/latest` branches. - Sync the affected upstream branch to Salsa, or propose it as a merge request if you aren't an Ubuntu developer. + Sync the affected upstream branch to Salsa, or push it to your fork and propose it as a merge request if you aren't an Ubuntu developer. ### Troubleshooting From 187184cba57c02706a906431e9fabc971b5f272a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Fri, 24 Oct 2025 17:00:56 +0200 Subject: [PATCH 32/48] Switch from git to gbp where relevant Co-authored-by: Marco Trevisan --- .../maintain-ubuntu-desktop-software.md | 20 +++++++++---------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index 5224eb03..b1f51406 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -172,7 +172,7 @@ When upstream releases a new version of a given project, you can merge the versi :host: :dir: gnome-control-center :user: - :input: git push --follow-tags + :input: gbp push origin ``` ### Merge a new upstream version to Debian @@ -229,7 +229,7 @@ If Debian doesn't have the new upstream version, add the release to Debian and U :host: :dir: gnome-control-center :user: - :input: git push --follow-tags + :input: gbp push origin ``` The `gbp` tool handles all branches automatically. In the example of this upstream release, `gbp` pushes the `ubuntu/latest`, `pristine-tarball` + `upstream/46.x` or `upstream/latest` branches. @@ -406,7 +406,7 @@ If `main` has a newer version than the maintenance branch and you are the first :host: :dir: gnome-control-center :user: - :input: git push --follow-tags + :input: gbp push origin ``` ### Add the maintenance version in Debian @@ -442,9 +442,7 @@ If the version doesn't exist in Debian yet, add it to Debian and Ubuntu using an :host: :dir: gnome-control-center :user: - :input: git push - - :input: git push -u upstream/46.x + :input: gbp push origin ``` 1. Push the `upstream` and `pristine-tar` branches to Salsa. @@ -456,7 +454,7 @@ If the version doesn't exist in Debian yet, add it to Debian and Ubuntu using an :host: :dir: gnome-control-center :user: - :input: git push --follow-tags + :input: gbp push origin ``` @@ -698,7 +696,7 @@ For a different patching workflow using the `quilt` tool, see {ref}`how-to-work- :host: :dir: gnome-control-center :user: - :input: git pull + :input: gbp pull origin ``` 1. Turn patches into commits: @@ -885,7 +883,7 @@ This procedure really needs a review. I rearranged the steps but I'm not sure if :host: :dir: gnome-control-center :user: - :input: git push + :input: gbp push origin ``` This pushes all needed branches, such as `ubuntu/latest`, and `pristine-tarball` + `upstream/latest` if this upload is a new upstream release. @@ -955,14 +953,14 @@ This procedure really needs a review. I rearranged the steps but I'm not sure if :input: git commit -a ``` -8. Push your changes to Salsa and track that branch: +8. Push your changes to Salsa: ```{terminal} :copy: :host: :dir: gnome-control-center :user: - :input: git push -u origin ubuntu/noble + :input: gbp push origin Total 0 (delta 0), reused 0 (delta 0) To git+ssh://git@salsa.debian.org:gnome-team/gnome-control-center From 01c4e9e74285037cbf31b17b77009d5a8ed07b50 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Fri, 24 Oct 2025 17:05:09 +0200 Subject: [PATCH 33/48] Switch from git to gbp where relevant --- docs/contributors/patching/maintain-ubuntu-desktop-software.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index b1f51406..4483179e 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -1095,7 +1095,7 @@ If this is a sponsored upload, the sponsor performs these steps. :host: :dir: gnome-control-center :user: - :input: git push + :input: gbp push origin ``` 1. Push the tags that we care about to Salsa: From de6d95d8a3362e103631bc42ae0766b2d5b4996b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Fri, 24 Oct 2025 17:05:56 +0200 Subject: [PATCH 34/48] Remove a step that's unnecessary with gbp Co-authored-by: Marco Trevisan --- .../patching/maintain-ubuntu-desktop-software.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index 4483179e..44c39940 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -1098,16 +1098,6 @@ If this is a sponsored upload, the sponsor performs these steps. :input: gbp push origin ``` -1. Push the tags that we care about to Salsa: - - ```{terminal} - :copy: - :host: - :dir: gnome-control-center - :user: - :input: git tag | grep -E '^ubuntu/|^debian/|^upstream/' | xargs -r git push - ``` - This pushes all tracked branches to Salsa if you made any changes. The branches include: * `ubuntu/latest` From 42086a9b5c0f508e9eaebd17e6de9bd90d7e0b19 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Fri, 24 Oct 2025 17:21:33 +0200 Subject: [PATCH 35/48] Apply review suggestions --- .../maintain-ubuntu-desktop-software.md | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index 44c39940..65ab6ca7 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -848,6 +848,29 @@ This procedure really needs a review. I rearranged the steps but I'm not sure if 1. Downloading the source tarball. + You can download the tarball that belongs to an Ubuntu release, like Noble: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: pull-lp-debs --download-only gnome-control-center noble + + Found gnome-control-center 1:46.7-0ubuntu0.24.04.3 in noble + Downloading gnome-control-center_46.7-0ubuntu0.24.04.3.dsc from archive.ubuntu.com (0.004 MiB) + ``` + + Or you can download the tarball based on a package version: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: pull-lp-debs --download-only gnome-control-center 46.7-0ubuntu0 + ``` + 1. Switch to the branch where you want to place this Ubuntu upload. 1. Import the tarball: From de3a9e3df6eb24d33e8a0acf8e006f26349dc6aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Fri, 24 Oct 2025 17:23:58 +0200 Subject: [PATCH 36/48] quilt is a legacy solution --- .../patching/maintain-ubuntu-desktop-software.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index 65ab6ca7..d985932e 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -542,6 +542,10 @@ The following steps work in both cases: You can turn patch files into commits on a branch. This enables you to add new patches or modify existing ones. +:::{note} +We recommend that you manage patches using the `gbp` tool on Ubuntu Desktop software, as described here. For the legacy patching workflow using the `quilt` tool, see {ref}`how-to-work-with-debian-patches`. +::: + 1. Switch to the correct `ubuntu/` branch or your local `experimental-feature` branch. For example: ```{terminal} @@ -636,10 +640,6 @@ You can turn patch files into commits on a branch. This enables you to add new p 1. The new patches end up as unstaged changes on your branch. Commit your changes. -### Additional resources - -For a different patching workflow using the `quilt` tool, see {ref}`how-to-work-with-debian-patches`. - ## Cherry-pick upstream commits From 6008f7582ccf503d1003e904096f0a41b7a45a5e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Fri, 24 Oct 2025 17:26:00 +0200 Subject: [PATCH 37/48] Installation steps can be smaller --- .../setup/set-up-git-for-ubuntu-desktop-work.md | 14 ++------------ 1 file changed, 2 insertions(+), 12 deletions(-) diff --git a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md index 7e7ec88b..271354c2 100644 --- a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md +++ b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md @@ -12,24 +12,14 @@ We'll use the Settings application as an example. Internally, the application is ## Initial setup -1. Install the basic packages for working in Git: +1. Install the basic packages for working in Git and Ubuntu packaging: ```{terminal} :copy: :host: :dir: :user: - :input: sudo apt install git git-buildpackage - ``` - -1. Install Ubuntu packaging tools: - - ```{terminal} - :copy: - :host: - :dir: - :user: - :input: sudo apt install gnupg pbuilder ubuntu-dev-tools apt-file + :input: sudo apt install git git-buildpackage ubuntu-dev-tools gnupg ``` For details about the packaging environment, see [Getting Set Up](https://canonical-ubuntu-packaging-guide.readthedocs-hosted.com/en/1.0/tutorial/getting-set-up.html) in the Ubuntu Packaging Guide. From 0b80489748d82c2e3a283be799844784f4da22e8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Fri, 24 Oct 2025 17:37:44 +0200 Subject: [PATCH 38/48] Cross-link GPG instructions --- .../setup/set-up-git-for-ubuntu-desktop-work.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md index 271354c2..72da6b0e 100644 --- a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md +++ b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md @@ -44,9 +44,14 @@ We'll use the Settings application as an example. Internally, the application is insteadof = salsa-gnome: ``` -1. Some projects might require that you sign tags with your GPG key. Enable automatic signing. - Display your public GPG key: +## Sign your commits + +Some projects might require that you sign tags with your GPG key. Enable automatic signing. + +1. Create your GPG key as described in {ref}`gnupg`. + +1. Display your public GPG key: ```{terminal} :copy: @@ -65,7 +70,7 @@ We'll use the Settings application as an example. Internally, the application is Your short GPG key ID is the last eight digits of your public GPG key, or `D1B76B89` in this example. - Add the following configuration to your `~/.gbp.conf` file: +1. Add the following configuration to your `~/.gbp.conf` file: ```{code-block} ini :caption: `~/.gbp.conf` From 79f286624d808b94e582c512c5114db0bad49e15 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Fri, 24 Oct 2025 17:55:15 +0200 Subject: [PATCH 39/48] freedesktop Git and cloning --- .../set-up-git-for-ubuntu-desktop-work.md | 27 +++++++++---------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md index 72da6b0e..2adeba98 100644 --- a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md +++ b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md @@ -30,7 +30,7 @@ We'll use the Settings application as an example. Internally, the application is This provides information about the source repository of every package so that you can easily clone it. -1. Enable the `salsa:name-or-team/repo` and `salsa-gnome:repo` short format for Salsa Git repositories. +1. Enable short formats for Git repositories: `salsa:name-or-team/repo` and `salsa-gnome:repo` for Salsa, `fdo:repo` for freedesktop\.org: Add the following configuration to your `~/.config/git/config` file: @@ -42,6 +42,9 @@ We'll use the Settings application as an example. Internally, the application is [url "git@salsa.debian.org:gnome-team/"] insteadof = salsa-gnome: + + [url "https://gitlab.freedesktop.org/"] + insteadof = fdo: ``` @@ -119,6 +122,7 @@ For details, see the `gbp.conf(5)` and `gbp-buildpackage` man pages. 1. If you don't have accounts on the following GitLab instances, create them: * [GNOME GitLab](https://gitlab.gnome.org/) is the upstream GNOME repository. + * [freedesktop\.org GitLab](https://gitlab.freedesktop.org/) hosts other desktop projects such as PipeWire. * [Salsa](https://salsa.debian.org/) hosts the Debian and Ubuntu packaging and modifications. It might take a while for your account to be approved. @@ -137,15 +141,12 @@ Let's clone the GNOME Control Center repository. :host: :dir: :user: - :input: apt-cache showsrc gnome-control-center | grep Vcs + :input: apt-cache showsrc gnome-control-center | grep-dctrl -n -s Vcs-Git - - Vcs-Browser: https://salsa.debian.org/gnome-team/gnome-control-center/tree/ubuntu/master - Vcs-Git: https://salsa.debian.org/gnome-team/gnome-control-center.git -b ubuntu/master - Debian-Vcs-Browser: https://salsa.debian.org/gnome-team/gnome-control-center - Debian-Vcs-Git: https://salsa.debian.org/gnome-team/gnome-control-center.git + https://salsa.debian.org/gnome-team/gnome-control-center.git -b ubuntu/master ``` - A link to a Git repository is attached to this package. We can clone it using the `debcheckout` tool. + A link to a Git repository is attached to this package. 2. Clone the repository from the Salsa remote: @@ -154,23 +155,21 @@ Let's clone the GNOME Control Center repository. :host: :dir: :user: - :input: debcheckout --git-track=* gnome-control-center + :input: gbp clone salsa-gnome:gnome-control-center - declared git repository at https://salsa.debian.org/gnome-team/gnome-control-center/ - git clone https://salsa.debian.org/gnome-team/gnome-control-center -b ubuntu/latest gnome-control-center ... - […] + gbp:info: Cloning from 'salsa-gnome:gnome-control-center' ``` - If the `Vcs-Git` field was missing or incorrect, you could clone the repository manually using `gbp`: + You can also use the repository link found earlier: ```{terminal} :copy: :host: :dir: :user: - :input: gbp clone salsa-gnome:gnome-control-center + :input: gbp clone https://salsa.debian.org/gnome-team/gnome-control-center.git - gbp:info: Cloning from 'salsa-gnome:gnome-control-center' + gbp:info: Cloning from 'https://salsa.debian.org/gnome-team/gnome-control-center.git' ``` From c0ed1b2f8c577297cf1c8479c2aa2b18772703dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Fri, 24 Oct 2025 18:04:02 +0200 Subject: [PATCH 40/48] Automatic changelog merge --- .../set-up-git-for-ubuntu-desktop-work.md | 91 ++++++++++++------- 1 file changed, 60 insertions(+), 31 deletions(-) diff --git a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md index 2adeba98..43282430 100644 --- a/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md +++ b/docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md @@ -86,37 +86,6 @@ Some projects might require that you sign tags with your GPG key. Enable automat Replace `GPGKEYID` with your short GPG key ID. -## Optional configuration - -The following configuration can simplify certain tasks on Ubuntu Desktop projects. - -Enable Git command aliases: - -```{code-block} ini -:caption: `~/.config/git/config` - -[alias] - matching-tags = "!f() { git for-each-ref --sort=creatordate --format '%(refname)' refs/tags| grep \"$1\"| sed s,^refs/tags/,,; }; f" - last-tags = matching-tags '.*' - last-match-tag = "!f() { git matching-tags $1 | tail -n1; }; f" - last-tag = last-match-tag '.*' - last-debian-tag = last-match-tag debian/ - last-ubuntu-tag = last-match-tag ubuntu/ - ubuntu-delta = "!f() { git diff $(git last-debian-tag) -- ${1:-debian} ':(exclude)debian/changelog'; }; f" -``` - -Export the `../build-area/` directory before building with the `git-buildpackage` tool: - -```{code-block} ini -:caption: `~/.gbp.conf` - -[buildpackage] -export-dir = ../build-area/ -``` - -For details, see the `gbp.conf(5)` and `gbp-buildpackage` man pages. - - ## Required accounts 1. If you don't have accounts on the following GitLab instances, create them: @@ -423,6 +392,66 @@ Branch 'upstreamvcs-main' set up to track remote branch 'main' from 'upstreamvcs Switched to a new branch 'upstreamvcs-main' ``` + +## Optional configuration + +The following configuration can simplify certain tasks on Ubuntu Desktop projects. + +### Git command aliases + +Enable Git command aliases: + +```{code-block} ini +:caption: `~/.config/git/config` + +[alias] + matching-tags = "!f() { git for-each-ref --sort=creatordate --format '%(refname)' refs/tags| grep \"$1\"| sed s,^refs/tags/,,; }; f" + last-tags = matching-tags '.*' + last-match-tag = "!f() { git matching-tags $1 | tail -n1; }; f" + last-tag = last-match-tag '.*' + last-debian-tag = last-match-tag debian/ + last-ubuntu-tag = last-match-tag ubuntu/ + ubuntu-delta = "!f() { git diff $(git last-debian-tag) -- ${1:-debian} ':(exclude)debian/changelog'; }; f" +``` + +### Exporting the build area + +Export the `../build-area/` directory before building with the `git-buildpackage` tool: + +```{code-block} ini +:caption: `~/.gbp.conf` + +[buildpackage] +export-dir = ../build-area/ +``` + +For details, see the `gbp.conf(5)` and `gbp-buildpackage` man pages. + +### Merging the changelog automatically + +To merge the changelog automatically, enable the `dpkg-mergechangelogs` tool in the `~/.config/git/config` file: + +```{code-block} ini +:caption: `~/.config/git/config` + +[merge "dpkg-mergechangelogs"] + name = debian/changelog merge driver + driver = dpkg-mergechangelogs -m %O %A %B %A +``` + +Create the `~/.config/git/attributes` file and set `dpkg-mergechangelogs` as the default strategy in it: + +```{code-block} ini +:caption: `~/.config/git/attributes` + +debian/changelog merge=dpkg-mergechangelogs +``` + +:::{warning} +This automation might not work when Ubuntu packages use a higher epoch than the Debian ones. In that case, fix the changelog manually. +::: + + ## Next steps Now that your Git setup is complete, you can contribute to Ubuntu Desktop software. You can build, modify, maintain and package applications. See {ref}`maintain-ubuntu-desktop-software`. From 25b22806f3d7d0f2ed914970bf4e867b86b84825 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Fri, 24 Oct 2025 18:09:20 +0200 Subject: [PATCH 41/48] Apply review suggestions --- .../maintain-ubuntu-desktop-software.md | 20 +++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index d985932e..58c8a965 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -186,11 +186,12 @@ If Debian doesn't have the new upstream version, add the release to Debian and U :host: :dir: gnome-control-center :user: - :input: uscan + :input: uscan --verbose --no-download + […] + Newest version of gnome-control-center on remote site is 49.1, local version is 46.7 => Newer package available from: - => https://download.gnome.org/sources/gnome-control-center/49/gnome-control-center-49.1.tar.xz - Successfully symlinked ../gnome-control-center-49.1.tar.xz to ../gnome-control-center_49.1.orig.tar.xz. + => https://download.gnome.org/sources/gnome-control-center/49/gnome-control-center-49.1.tar.xz ``` 1. Is `uscan` showing the upstream release that you want to import? @@ -382,11 +383,14 @@ If `main` has a newer version than the maintenance branch and you are the first :host: :dir: gnome-control-center :user: - :input: git remote show origin + :input: git tag -l | grep upstream - […] - upstream/46.2 pushes to upstream/46.2 (up to date) - […] + […] + upstream/46.0 + upstream/46.0.1 + upstream/46.1 + upstream/46.3 + […] ``` 1. If the version already exists in Debian, use Debian's upstream branch tags: @@ -396,7 +400,7 @@ If `main` has a newer version than the maintenance branch and you are the first :host: :dir: gnome-control-center :user: - :input: git merge upstream/46.2 -m "Update upstream source from tag 'upstream/46.2'" + :input: git merge upstream/46.3 -m "Update upstream source from tag 'upstream/46.3'" ``` Push the `upstream` and `pristine-tar` branches to Salsa: From 67e17295b5190bdd8324216e63dfcac5ef594f11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Fri, 24 Oct 2025 18:16:06 +0200 Subject: [PATCH 42/48] Check for dependency changes --- .../patching/maintain-ubuntu-desktop-software.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index 58c8a965..59eb78fa 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -237,6 +237,22 @@ If Debian doesn't have the new upstream version, add the release to Debian and U Sync the affected upstream branch to Salsa, or push it to your fork and propose it as a merge request if you aren't an Ubuntu developer. +### Check for dependency changes + +New upstream releases often change the dependencies of the application. Check for changes. + +For example, if the application uses the Meson build system and you've updated from version `49.alpha` to `49.0`: + +```{terminal} +:copy: +:host: +:dir: gnome-control-center +:user: +:input: git diff 49.alpha..49.0 -- meson.build +``` + +Reflect the application changes in the package dependencies. + ### Troubleshooting You might get the following errors when importing the tarball. From 14614c1ee7b1c4e9a6f0e91ad5067321ce142075 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Fri, 24 Oct 2025 18:22:02 +0200 Subject: [PATCH 43/48] Manual patches --- .../patching/maintain-ubuntu-desktop-software.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index 59eb78fa..ecae64cc 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -556,6 +556,16 @@ The following steps work in both cases: 1. Commit the changes. +If the `--time-machine` step or `gbp pq rebase` fail, you can import the patches into the `pq` branch manually from a file: + +```{terminal} +:copy: +:host: +:dir: gnome-control-center +:user: +:input: git am -3 < debian/patches/ +``` + (desktop-git-add-or-modify-patches)= ## Add or modify patches From 1d508f3dd1ff0dd06ca047e0975f20a84136af71 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Fri, 24 Oct 2025 18:24:05 +0200 Subject: [PATCH 44/48] Better step nesting --- .../maintain-ubuntu-desktop-software.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index ecae64cc..43e35f06 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -542,6 +542,16 @@ The following steps work in both cases: 1. Resolve the conflict using `git add` and `git rm`. 1. Proceed with `git rebase --continue`. +1. If the `--time-machine` step or `gbp pq rebase` fail, you can import the patches into the `pq` branch manually from a file: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: git am -3 < debian/patches/ + ``` + 1. Regenerate the `debian/patches` data, ready to be committed: ```{terminal} @@ -556,16 +566,6 @@ The following steps work in both cases: 1. Commit the changes. -If the `--time-machine` step or `gbp pq rebase` fail, you can import the patches into the `pq` branch manually from a file: - -```{terminal} -:copy: -:host: -:dir: gnome-control-center -:user: -:input: git am -3 < debian/patches/ -``` - (desktop-git-add-or-modify-patches)= ## Add or modify patches From 7e3f10f13f7eee2319b713b6d5a86324715ba6b1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Fri, 24 Oct 2025 18:28:00 +0200 Subject: [PATCH 45/48] Apply review suggestions --- .../patching/maintain-ubuntu-desktop-software.md | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index 43e35f06..7ba1a0f8 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -673,6 +673,8 @@ We recommend that you manage patches using the `gbp` tool on Ubuntu Desktop soft ## Cherry-pick upstream commits +You can cherry-pick an upstream commit into a patch file. + 1. Refresh the upstream repository. We don't have a local checkout, only a remote that we need to refresh: @@ -707,8 +709,6 @@ We recommend that you manage patches using the `gbp` tool on Ubuntu Desktop soft :input: git log -p upstreamvcs/master ``` -1. Cherry-pick a commit as a patch. For example, on the `ubuntu/latest` branch: - 1. Switch to the branch where you want to add the cherry-picked commit. For example, on the `ubuntu/latest` branch: ```{terminal} @@ -753,7 +753,7 @@ We recommend that you manage patches using the `gbp` tool on Ubuntu Desktop soft ``` ::: -1. Display the upstream Git log in the patch format: +1. Display the upstream Git log in the patch format. Note the hash of the commit that you want to cherry-pick: ```{terminal} :copy: @@ -763,11 +763,6 @@ We recommend that you manage patches using the `gbp` tool on Ubuntu Desktop soft :input: git log -p upstream/latest ``` - :::{admonition} TODO - :class: attention - What is this for? It seems to just display the log without affecting your repository in any way. - ::: - 1. Cherry-pick your selected commit using its hash and edit the commit message: ```{terminal} From 669ada6f16618005f1de86717f9543f0b1d52c4c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Fri, 24 Oct 2025 22:12:36 +0200 Subject: [PATCH 46/48] Cherry-picking review --- .../maintain-ubuntu-desktop-software.md | 52 +------------------ 1 file changed, 2 insertions(+), 50 deletions(-) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index 7ba1a0f8..aa8855d0 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -675,40 +675,6 @@ We recommend that you manage patches using the `gbp` tool on Ubuntu Desktop soft You can cherry-pick an upstream commit into a patch file. -1. Refresh the upstream repository. - - We don't have a local checkout, only a remote that we need to refresh: - - ```{terminal} - :copy: - :host: - :dir: gnome-control-center - :user: - :input: git fetch upstreamvcs - ``` - -1. Find the commits that you want to cherry-pick. Browse the Git history. - - For example, look at the Git log of the `main` branch: - - ```{terminal} - :copy: - :host: - :dir: gnome-control-center - :user: - :input: git log -p upstreamvcs/main - ``` - - Many GNOME projects now use `main` instead of `master`. If your project is still using `master`, adjust the branch: - - ```{terminal} - :copy: - :host: - :dir: gnome-control-center - :user: - :input: git log -p upstreamvcs/master - ``` - 1. Switch to the branch where you want to add the cherry-picked commit. For example, on the `ubuntu/latest` branch: ```{terminal} @@ -736,22 +702,8 @@ You can cherry-pick an upstream commit into a patch file. :host: :dir: gnome-control-center :user: - :input: gbp pq rebase - ``` - - :::{note} - Instead, you can also use the following commands. This deletes your patch queue and re-creates it from `debian/patches`, which can be useful if the `patch-queue` branch gets out of sync with `latest`: - - ```{terminal} - :copy: - :host: - :dir: gnome-control-center - :user: - :input: gbp pq drop - - :input: gbp pq import + :input: gbp pq rebase || gbp pq import ``` - ::: 1. Display the upstream Git log in the patch format. Note the hash of the commit that you want to cherry-pick: @@ -770,7 +722,7 @@ You can cherry-pick an upstream commit into a patch file. :host: :dir: gnome-control-center :user: - :input: git cherry-pick -e -x + :input: git cherry-pick -x ``` 1. Are there any conflicts? From 79b68ac9950e57cbbbb6171a8fd48c3dcc5cfbab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Fri, 24 Oct 2025 22:22:18 +0200 Subject: [PATCH 47/48] Apply review suggestions --- .../patching/maintain-ubuntu-desktop-software.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index aa8855d0..f366daef 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -971,7 +971,7 @@ This procedure really needs a review. I rearranged the steps but I'm not sure if ## Build a package locally -To build a local package, we use the `sbuild` framework and specify the target Ubuntu release. We don't recommend building the package directly on your system without using `sbuild` because the test and build phase might be affected by the state of your machine. +To build a local package, we use the [`sbuild` framework](https://canonical-ubuntu-packaging-guide.readthedocs-hosted.com/en/1.0/how-to/setting-up-sbuild.html) and specify the target Ubuntu release. We don't recommend building the package directly on your system without using `sbuild` because the test and build phase might be affected by the state of your machine. * Build a binary package for your Ubuntu release and CPU architecture. For example, Ubuntu Noble on the AMD64 architecture: @@ -1074,6 +1074,16 @@ If this is a sponsored upload, the sponsor performs these steps. :input: gbp buildpackage -S ``` + If this version hasn't appeared in the `main` repository yet, include both the Ubuntu and Debian part of the changelog in the `.changes` file, which is generated by `dpkg-genchanges`. Add the `-vX` option to include all Debian and Ubuntu versions greater than `X`: + + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp buildpackage -S -vX + ``` + 1. Check the `../build-area/.changes` file to make sure that it's correct. This file instructs `dput` which files to upload, and provides a high-level view of the changes such as the latest changelog entries. For example, changes to the GNU Hello program as packaged for Ubuntu would be described in the `hello_2.10-0ubuntu1.changes` file. From 6d9efad43233daa140d1ce961e056c2f200b7d4e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Fri, 24 Oct 2025 22:42:43 +0200 Subject: [PATCH 48/48] Apply review suggestions --- .../maintain-ubuntu-desktop-software.md | 42 ++++++++----------- 1 file changed, 18 insertions(+), 24 deletions(-) diff --git a/docs/contributors/patching/maintain-ubuntu-desktop-software.md b/docs/contributors/patching/maintain-ubuntu-desktop-software.md index f366daef..7dde88c7 100644 --- a/docs/contributors/patching/maintain-ubuntu-desktop-software.md +++ b/docs/contributors/patching/maintain-ubuntu-desktop-software.md @@ -482,23 +482,21 @@ If the version doesn't exist in Debian yet, add it to Debian and Ubuntu using an Before merging with an upstream release, refresh the patches. -If your `patch/queue` branch is in sync with the previous release, you can just rebase: +1. Rebase the `pq` branch: -```{terminal} -:copy: -:host: -:dir: gnome-control-center -:user: -:input: gbp pq rebase -``` - -Then you can use the Git rebase tools to refresh the patches. + ```{terminal} + :copy: + :host: + :dir: gnome-control-center + :user: + :input: gbp pq rebase + ``` -For the case of using `gbp import-orig`, this is better described in the [`gbp` documentation](https://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.patches.newupstream.html). +1. Use the Git rebase tools to refresh the patches. -This might not work if you're instead merging with an `upstream/x.z.y` tag or if you didn't create the `patch/queue` branch first. +### Troubleshooting -The following steps work in both cases: +The rebase might not work in certain cases, such as if you're merging with an `upstream/x.z.y` tag or if you didn't create the `patch/queue` branch first. In those cases, follow these steps: 1. Switch to the corresponding branch. @@ -512,7 +510,7 @@ The following steps work in both cases: :input: gbp pq drop ``` -1. Try to find the first point where the patches merge. Increase the value until you don't find the previous release commit: +1. Try to find the earliest point where the patches still apply. Increase the value until you don't find the previous release commit: ```{terminal} :copy: @@ -522,10 +520,7 @@ The following steps work in both cases: :input: gbp pq import --force --time-machine=30 ``` - :::{admonition} TODO - :class: attention - How much should you increase the value and how can you tell that you should stop? - ::: + Replace `30` with a number that determines how far in history you want to look for the patches. The exact number depends on the size of your repository. Larger numbers provide better results but the search gets increasingly slow so start small. 1. Re-apply the `debian/patches/series` file on top of the new upstream code, stopping for manual action if is needed: @@ -552,7 +547,7 @@ The following steps work in both cases: :input: git am -3 < debian/patches/ ``` -1. Regenerate the `debian/patches` data, ready to be committed: +1. Regenerate the `debian/patches` data: ```{terminal} :copy: @@ -566,6 +561,10 @@ The following steps work in both cases: 1. Commit the changes. +### See also + +[Importing a new upstream version](https://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.patches.newupstream.html) in the `gbp` documentation. + (desktop-git-add-or-modify-patches)= ## Add or modify patches @@ -818,11 +817,6 @@ Then, filter them out by hand at the commit phase. You can import a Debian Source Control (DSC) source package as a tarball, even if it doesn't exist in the Git version tracking system (VCS). -:::{admonition} TODO -:class: attention -This procedure really needs a review. I rearranged the steps but I'm not sure if they still work. -::: - 1. Downloading the source tarball. You can download the tarball that belongs to an Ubuntu release, like Noble: