Add Ubuntu Desktop workflows #229

msuchane · 2025-10-13T17:02:39Z

Description

This PR adds Git, patching and packaging workflows migrated from the Ubuntu wiki: https://wiki.ubuntu.com/DesktopTeam/git

These guides are mainly written for the Ubuntu Desktop Team but community contributors can also follow them.

Some of the content is similar in its overall purpose to existing Ubuntu Project guides but the Desktop and GNOME workflow is distinct.

Related issue

https://warthogs.atlassian.net/browse/UDENG-6342

Checklist

I have read and followed the Ubuntu Project contributing guide
My pull request is linked to an existing issue (if applicable)
I have tested my changes, and they work as expected

Additional notes (optional)

This documentation needs one final review by Desktop Team members. It's a draft for now.

We can adjust the placement of the files in the documentation set. I realize they don't fit too neatly.

quine00

Thanks for working on this! Comments in-line.

docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md

quine00

Partial review, will come back later. Thanks!

quine00 · 2025-10-14T07:02:05Z

docs/contributors/patching/maintain-ubuntu-desktop-software.md

+* 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.
+


Should we describe how to also remove local changes? dh_clean is apparently supposed to do that, but some packages don't. I often use git checkout . && git clean -fd . && quilt -f pop -a to reset things if I don't care about what has changed. Sure there's better ways!

Sounds good. Until I learn about better commands, I'm using your two suggestions.

Well, removing local changes (as debian changes) is not needed, since when building everything is only in the build directory which is detached from this (it's the beauty of gbp).

If it's about removing git local changes, well that's imho out of scope of the guide, since using git clean is not really something strictly related to packaging.

Thanks @3v1n0. I'm not sure what use case we're trying to solve here. @quine00, should we just delete the step to remove local changes then?

I'm for deleting all this, quilt is a no-no in this workflow (that exists exactly not to have to deal with it`

docs/contributors/patching/maintain-ubuntu-desktop-software.md

msuchane · 2025-10-15T11:30:16Z

Thanks @quine00 for the review so far!

Sally and Robert, please take a look if the placement within the documentation set is appropriate. I chose the patching folder for the maintenance guide because that seemed like the closest fit.

docs/contributors/patching/maintain-ubuntu-desktop-software.md

docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md

docs/contributors/patching/maintain-ubuntu-desktop-software.md

3v1n0 · 2025-10-16T14:14:17Z

docs/contributors/patching/maintain-ubuntu-desktop-software.md

+(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.


This is not wrong, you only have to gbp import-origin --uscan (or using the tarball) or either to merge with debian/latest, but you don't have to do the ubuntu/latest merge manually

Do you have to be a Debian Developer in order to merge into debian/latest?

No, anyone could in theory, but in practice only debian developers / maintainers should do it directly. For others MRs are welcome!

docs/contributors/patching/maintain-ubuntu-desktop-software.md

Co-authored-by: Marco Trevisan <[email protected]>

…untu-project-docs into desktop-git-guide-UDENG-6342

3v1n0 · 2025-10-23T15:01:06Z

docs/contributors/patching/maintain-ubuntu-desktop-software.md

+    :host:
+    :dir: gnome-control-center
+    :user:
+    :input: git push --follow-tags


Suggested change

:input: git push --follow-tags

:input: gbp push origin

3v1n0 · 2025-10-23T15:01:30Z

docs/contributors/patching/maintain-ubuntu-desktop-software.md

+    :host:
+    :dir: gnome-control-center
+    :user:
+    :input: git push --follow-tags


Suggested change

:input: git push --follow-tags

:input: gbp push origin

3v1n0 · 2025-10-23T15:02:20Z

docs/contributors/patching/maintain-ubuntu-desktop-software.md

+    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):


Suggested change

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 (`gbp` handles this automatically, so that `ubuntu/latest`, `pristine-tarball` + `upstream/46.x` or `upstream/latest` if this upload is a new upstream release are handled):

3v1n0 · 2025-10-23T15:02:35Z

docs/contributors/patching/maintain-ubuntu-desktop-software.md

+    :host:
+    :dir: gnome-control-center
+    :user:
+    :input: git push --follow-tags


Suggested change

:input: git push --follow-tags

:input: gbp push origin

3v1n0 · 2025-10-23T15:03:10Z

docs/contributors/patching/maintain-ubuntu-desktop-software.md

+    :input: git push
+
+    :input: git push -u upstream/46.x


Suggested change

:input: git push

:input: git push -u upstream/46.x

:input: gbp push origin

3v1n0 · 2025-10-23T15:05:57Z

docs/contributors/patching/maintain-ubuntu-desktop-software.md

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


Suggested change

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

```

3v1n0 · 2025-10-23T15:07:42Z

docs/contributors/patching/maintain-ubuntu-desktop-software.md

+* 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.
+


I'm for deleting all this, quilt is a no-no in this workflow (that exists exactly not to have to deal with it`

3v1n0 · 2025-10-23T15:08:22Z

docs/contributors/patching/maintain-ubuntu-desktop-software.md

+    :host:
+    :dir: gnome-control-center
+    :user:
+    :input: git pull


Suggested change

:input: git pull

:input: gbp pull origin

3v1n0 · 2025-10-23T15:11:33Z

docs/contributors/patching/maintain-ubuntu-desktop-software.md

+    ```{terminal}
+    :copy:
+    :host:
+    :dir: gnome-control-center
+    :user:
+    :input: git remote show origin
+
+        […]
+        upstream/46.x            pushes to upstream/46.x            (up to date)
+        […]
+    ```


I would just git tag -l | grep debian or git tag -l | grep upstream

3v1n0 · 2025-10-23T15:13:34Z

docs/contributors/patching/maintain-ubuntu-desktop-software.md

+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 use pull-lp-debs --download-only <source-package> [ubuntu-version] [version] like pull-lp-debs --download-only glib noble or pull-lp-debs --download-only gnome-shell 49.0-1ubuntu0

Add Ubuntu Desktop workflows

e4c389b

quine00 reviewed Oct 14, 2025

View reviewed changes

msuchane added 6 commits October 15, 2025 11:55

Explain the short GPG key

fe248a3

latest can also be called main or master

0094543

Clarify upstreamvcs branches

7312f40

Unnecessary words

5c289a8

How to reset local changes

3945677

Clarify pushing to Salsa

7a00551

msuchane marked this pull request as ready for review October 15, 2025 11:28

msuchane requested review from rkratky and s-makin as code owners October 15, 2025 11:28

msuchane and others added 3 commits October 15, 2025 14:50

Fix a typo

3003d0c

Add unstaged to the dictionary

fd2f29e

Clarify dpkg-genchanges -v.

8331764

nteodosio reviewed Oct 16, 2025

View reviewed changes

docs/contributors/patching/maintain-ubuntu-desktop-software.md Outdated Show resolved Hide resolved

nteodosio reviewed Oct 16, 2025

View reviewed changes

docs/contributors/patching/maintain-ubuntu-desktop-software.md Outdated Show resolved Hide resolved

nteodosio reviewed Oct 16, 2025

View reviewed changes

docs/contributors/patching/maintain-ubuntu-desktop-software.md Outdated Show resolved Hide resolved

msuchane added 4 commits October 16, 2025 13:12

Front-load the use case

4166717

Clarify a step

60a4c67

Apply feedback

2daad3c

Add a note about debian/control.in

b64aca5

3v1n0 reviewed Oct 16, 2025

View reviewed changes

docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md Show resolved Hide resolved

3v1n0 reviewed Oct 16, 2025

View reviewed changes

docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md Show resolved Hide resolved

3v1n0 reviewed Oct 16, 2025

View reviewed changes

docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md Outdated Show resolved Hide resolved

3v1n0 reviewed Oct 16, 2025

View reviewed changes

docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md Outdated Show resolved Hide resolved

3v1n0 reviewed Oct 16, 2025

View reviewed changes

docs/contributors/setup/set-up-git-for-ubuntu-desktop-work.md Outdated Show resolved Hide resolved

3v1n0 reviewed Oct 16, 2025

View reviewed changes

docs/contributors/patching/maintain-ubuntu-desktop-software.md Outdated Show resolved Hide resolved

3v1n0 reviewed Oct 16, 2025

View reviewed changes

docs/contributors/patching/maintain-ubuntu-desktop-software.md Outdated Show resolved Hide resolved

3v1n0 reviewed Oct 16, 2025

View reviewed changes

docs/contributors/patching/maintain-ubuntu-desktop-software.md Outdated Show resolved Hide resolved

3v1n0 reviewed Oct 16, 2025

View reviewed changes

msuchane and others added 17 commits October 16, 2025 19:54

Missing Git option

3a4e87e

Co-authored-by: Marco Trevisan <[email protected]>

Apply review suggestions

b9d1627

Apply review suggestions

ead03f4

Apply review suggestions

99a0892

Fix gbp options

85e621a

Co-authored-by: Marco Trevisan <[email protected]>

Apply review suggestions

eee2e72

Fix gbp options

005dab5

Co-authored-by: Marco Trevisan <[email protected]>

More precise use case

8bcebc3

Co-authored-by: Marco Trevisan <[email protected]>

Apply review suggestions

40d5b41

Add a file name

3c4367b

Co-authored-by: Marco Trevisan <[email protected]>

Apply review suggestions

9ee5b6d

Merge branch 'desktop-git-guide-UDENG-6342' of github.com:msuchane/ub…

0c512bd

…untu-project-docs into desktop-git-guide-UDENG-6342

Apply review suggestions

d881393

Remove unnecessary information

707ea7d

Resolving TODO items

e35fe98

Typo

4b8c9bb

The branches summary was unnecessary

2e5ca8c

3v1n0 reviewed Oct 23, 2025

View reviewed 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.

	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 (`gbp` handles this automatically, so that `ubuntu/latest`, `pristine-tarball` + `upstream/46.x` or `upstream/latest` if this upload is a new upstream release are handled):

Add Ubuntu Desktop workflows #229

Are you sure you want to change the base?

Add Ubuntu Desktop workflows #229

Conversation

msuchane commented Oct 13, 2025

Description

Related issue

Checklist

Additional notes (optional)

Uh oh!

quine00 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

quine00 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

msuchane commented Oct 15, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!