Migrated git-ubuntu docs

docs/conf.py

@@ -402,10 +402,7 @@
         None,
     ),
     "sru": ("https://canonical-sru-docs.readthedocs-hosted.com/en/latest/", None),
-    "git-ubuntu": (
-        "https://canonical-git-ubuntu.readthedocs-hosted.com/en/latest/",
-        None,
-    ),
+    "launchpad": ("https://documentation.ubuntu.com/launchpad/", None),
 }
 
 

docs/contributors/advanced/handle-git-ubuntu-uploads.md

@@ -0,0 +1,241 @@
+(how-to-handle-git-ubuntu-uploads)=
+# How to handle `git-ubuntu` uploads
+
+git-ubuntu is tooling that provides unified git-based workflows for the development of Ubuntu source packages. Use git-ubuntu for inspecting, working on, or contributing to Ubuntu source packages.
+
+See {ref}`how-to-set-up-for-ubuntu-development` for basic prerequisites.
+
+
+## Handle contributions using git-ubuntu
+
+The following is a typical workflow for handling a git-ubuntu-based
+contribution:
+
+1. Clone the source package's official git-ubuntu repository
+1. Add the contributor's remote tracking branch branch to the checkout
+1. Review the branch
+1. Build the proposed source package
+1. Run autopkgtests
+
+These steps are described in the sections below.
+
+
+## Checkout the source package's official git-ubuntu repo
+
+```console
+git ubuntu clone <package> [dir-name]
+```
+
+For example, for a contribution to dovecot, you might run:
+
+```console
+git ubuntu clone dovecot
+```
+
+
+## Add remote tracking branches to a git-ubuntu source repo
+
+In order to review the sponsoree's changes, you'll want to add their
+Launchpad username to your local checkout:
+
+```console
+git ubuntu remote add $sponsoree $url
+git switch -c lp$id-$desc-$release $sponsoree/$branch_name
+```
+
+
+## View the current state of the package for a given release
+
+By default the `git ubuntu clone` command will checkout a branch named
+'ubuntu/devel' that corresponds to the current Ubuntu development
+release.  If you wish to examine the version of the source package for a
+different Ubuntu version, git-ubuntu provides branches tracking all
+releases and pockets.  For example:
+
+```console
+git branch -av | grep pkg/ubuntu/jammy
+remotes/pkg/ubuntu/jammy            17f59d728 1:2.3.16+dfsg1-3ubuntu2 (patches unapplied)
+remotes/pkg/ubuntu/jammy-devel      f5217e4fc changelog
+remotes/pkg/ubuntu/jammy-proposed   f5217e4fc changelog
+remotes/pkg/ubuntu/jammy-security   20252305d 1:2.3.16+dfsg1-3ubuntu2.1 (patches unapplied)
+remotes/pkg/ubuntu/jammy-updates    f5217e4fc changelog
+```
+
+Most commonly, it will be the -devel branch you're interested in for
+patch piloting work, so in general for the current jammy version of the
+package, you would typically want to run:
+
+```console
+git switch -c jammy-devel pkg/ubuntu/jammy-devel
+```
+
+Be aware that the -devel branch will include any changes currently
+staged in -proposed that haven't been released yet.  If the git hash
+for -devel doesn't match with at least one of the release pockets, that
+may indicate this discrepancy.  In that case, some additional action may
+be needed before the new changes can be uploaded.
+
+
+(convert-a-debdiff-contribution-into-a-git-ubuntu-branch)=
+## Convert a debdiff contribution into a git-ubuntu branch
+
+Traditional contributions to Patch Pilot are in debdiff form, and in
+terms of policy may be fine to handle directly, without use of
+git-ubuntu.  However, if you prefer to handle it through git-ubuntu, you
+may find the following workflow useful.
+
+1. Clone the package and apply the debdiff:
+
+   ```console
+   git ubuntu clone $package && cd $package
+   git switch -c lp$bugnumber-$description-$release pkg/ubuntu/$release-devel
+
+   debdiff-apply < ../$debdiff_file
+   ```
+
+1. Create cleaned up commits (except changelog and maintainer):
+
+   ```console
+   git add -p ...
+   git commit
+
+   git commit debian/changelog -m changelog
+   ```
+
+1. If there was no Debian delta before:
+
+   ```console
+   update-maintainer
+   git commit debian/control* -m "update-maintainer"
+   ```
+
+That should result in a reasonable facsimile of a git ubuntu style
+branch.  Depending on the contribution you might want to improve the
+commit message or split the changes up into several commits instead of
+one.
+
+Once you're happy, the branch is proposed for merging on launchpad, so it can be reviewed and uploaded.
+
+For more info about traditional debdiff-based contributing, see the
+[Reviewer Team's Knowledge Base](https://wiki.ubuntu.com/ReviewersTeam/KnowledgeBase).
+
+
+(restore-empty-directories)=
+## Restore empty directories
+
+The experimental `git-ubuntu.experimental-emptydirfixup` tool restores
+the empty directories locally as a workaround to the {ref}`empty directory problem <empty-directories>`. It takes a non-merge commit and
+examines its parent to examine what empty directories have been lost. It
+provides an equivalent replacement commit.
+
+Run it with `fix-head` to replace `HEAD` with a commit that has empty
+directories restored.
+
+Run it with `fix-many` and a parameter pointing to a base commit to run
+`git-rebase` to fix a set of commits.
+
+Note that in both cases, the parent must have the empty directories in order
+for them to be copied down through the fixed up commits. In the common case
+where this tool is needed, you'll be starting from an "official" git-ubuntu
+import tag or branch, so this will be true in these cases. However, this does
+mean that you need to use `fix-many` all the way back to the first commit
+after such an "official" commit. If you have intermediary un-fixed commits and
+then just try to apply `fix-head` to the end, then it won't work as the
+empty directories won't get copied forward.
+
+Example of use:
+
+```console
+git ubuntu clone apache2 && cd apache2
+git tag -f base
+  <add commits>
+git-ubuntu.experimental-emptydirfixup fix-many base
+debuild -S $(git ubuntu prepare-upload args)
+```
+
+
+## Build a git-ubuntu source package branch for uploading
+
+Check out the branch to build, maybe adjust `debian/changelog` to contain `~ppa1` as suffix, then build the source package:
+
+```console
+git ubuntu export-orig [--for-merge]
+debuild -S -d $(git ubuntu prepare-upload args)
+```
+
+Following this workflow, with use of prepare-upload, the rich history
+in the git commit log will be preserved and shared with other packagers,
+and the merge proposal will get marked merged automatically.
+
+To install build dependencies, you either:
+* use `apt-get build-dep $package`
+* or, for considering current changes to `debian/control`, use `install-build-deps` script from [ubuntu-helpers repository](https://git.launchpad.net/~ubuntu-server/+git/ubuntu-helpers), or download it [directly](https://git.launchpad.net/~ubuntu-server/+git/ubuntu-helpers/plain/bryce/install-build-deps).
+
+
+## Run autopkgtests against a git-ubuntu branch
+
+Here's a workflow snippet to toss the changes into a PPA and run tests
+on that:
+
+```console
+ppaid="ppa:<username>/<package>-review-lp<num>"
+ppa create $ppaid
+dput $ppaid $package.changes
+ppa wait $ppaid
+ppa tests $ppaid
+```
+
+The last command will print clickable links to trigger the corresponding
+autopkgtests.  When triggering them, keep in mind not all architectures
+may be available in the PPA build.
+
+If someone has already provided a PPA with a successfully built package,
+you can skip most of that and just run the last command.  If another
+pilot has already run the tests, then that'll print the results.
+
+Since autopkgtests can take a while to run, you may want to consider
+triggering them and then handing off the remainder of the review to the
+next patch pilot.
+
+
+## Close someone's git-ubuntu MP
+
+Ask for the the MP to be closed for you, with an
+explanation as to why and whether it should be set to Merged or Rejected.
+
+Canonical employees: in Mattermost on the "Patch Pilot v2" channel, mention
+`git-ubuntu-help` to request this.
+
+General public: use #ubuntu-devel on Libera.Chat, mentioning
+`git-ubuntu-help`.
+
+For example:
+
+```none
+git-ubuntu-help please mark
+https://code.launchpad.net/~abc/ubuntu/+source/hello/+git/foo/+merge/123
+as merged as it has been uploaded.
+```
+
+
+## Find out why a git-ubuntu package repository is not up-to-date
+
+1. Check `https://git.launchpad.net/ubuntu/+source/<package>` to see when
+   git-ubuntu last updated the package repository.
+1. Check `https://launchpad.net/ubuntu/+source/<package>/+publishinghistory` to
+   see when the package was last updated by Launchpad.
+1. Ask an admin if it's pending or with an error in the queue.
+1. If there are no other signs, then developer debug is probably necessary.
+
+
+## Deal with a package version deleted from the Archive
+
+See {lpbug}`1852389`.
+
+* Base on what is appropriate; both the deleted version and the currently
+  present version may be fine, depending on why the deletion was performed.
+* Rich history import won't be affected; it just expects your changelog parent
+  to match your rich history base, and that'll generally be true anyway.
+* You can't upload the same version that was deleted, so you may need to "jump"
+  past that version. Exception: in a stable release, ubuntu1 -> ubuntu2
+  (deleted) -> ubuntu1.1 works.

docs/contributors/advanced/index.md

@@ -17,13 +17,15 @@ check-reverse-dependencies
 ```
 
 
-## Sponsorship
+## Sponsorship and uploading
 
 See the {ref}`sponsorship` article series for instructions on how seek sponsorship as well as review and sponsor uploads and syncs.
 
 ```{toctree}
 :maxdepth: 1
 
+Handle git-ubuntu contributions <handle-git-ubuntu-uploads>
+Upload with rich history <upload-with-rich-history>
 Review a merge proposal <review-a-merge-proposal>
 Sponsor an upload <sponsor-an-upload>
 Sponsor a sync <sponsor-a-sync>

docs/contributors/advanced/sponsor-an-upload.md

@@ -29,7 +29,7 @@ If you are interested in {ref}`sponsoring <sponsorship>`, and have gained upload
 This is similar to uploading your own `.changes` file, except that after ensuring the upload follows all quality standards (see {ref}`how-to-review-a-merge-proposal`), you sign the content of the proposing person with your key and upload it to the Ubuntu Archive instead of a PPA.
 
 :::{note}
-These instructions assume the request for sponsorship is in the form of a {term}`merge proposal`. See *How can I convert a debdiff contribution into a git-ubuntu branch?* under {external+git-ubuntu:doc}`howto/patch-pilot` for guidance on working with a 'traditional' contribution in the form of a patch generated by the {manpage}`debdiff(1)` tool.
+These instructions assume the request for sponsorship is in the form of a {term}`merge proposal`. See {ref}`convert-a-debdiff-contribution-into-a-git-ubuntu-branch` for guidance on working with a 'traditional' contribution in the form of a patch generated by the {manpage}`debdiff(1)` tool.
 :::
 
 1. Clone the package repository and change to the created directory:
@@ -150,4 +150,4 @@ The {command}`debsign` and {command}`dpkg-buildpackage` tools use similar variab
 
 ## Further reading
 
-* {external+git-ubuntu:doc}`index`
+* {ref}`how-to-handle-git-ubuntu-uploads`

docs/contributors/advanced/upload-with-rich-history.md

@@ -0,0 +1,99 @@
+(how-to-upload-with-rich-history)=
+# How to upload with rich history
+
+See the {ref}`rich history explanation <rich-history>` for context.
+
+:::{admonition} Not retaining rich history
+:class: note
+This applies to all workflows described below
+
+If you don't wish to retain your rich history branch in Launchpad, you must
+wait for the importer to retrieve it before you delete it. To be sure of the
+timing, wait until after the rich history has appeared in the official
+repository.
+:::
+
+
+## Standard workflow
+
+These instructions make the following assumptions:
+
+1. You had originally used `git ubuntu clone` to clone your repository.
+1. You have a local branch checked out and your working directory is clean.
+1. A previous git-ubuntu commit is an ancestor of your current commit.
+1. You are at the top level of your source tree that is ready to build.
+
+Push your branch, create the source package and changes file and upload them as
+follows:
+
+```console
+dpkg-buildpackage -S $your_options $(git ubuntu prepare-upload args)
+dput ubuntu ../<package>_<version>_source.changes
+```
+
+`git ubuntu prepare-upload args` will push your branch to your namespace
+on Launchpad with the same remote branch name, and then output the appropriate
+arguments for `dpkg-buildpackage` to include the appropriate reference to
+the rich history in the changes file. See
+{ref}`changes-file-headers`.
+
+
+## Manual workflow
+
+These instructions make the following assumptions:
+
+1. A previous git-ubuntu commit is an ancestor of your current commit.
+1. You have made a branch available at a public git URL on Launchpad that
+   contains the rich history that will match your upload.
+1. You are at the top level of your source tree that is ready to build.
+
+Identify three items:
+
+1. The publicly available URL on Launchpad to the git repository that contains
+   your commit. This **must** begin with `https://git.launchpad.net/`.
+1. A ref under which your commit can be found. For example, if you have pushed
+   to a branch called `my-feature`, the ref would be
+   `refs/heads/my-feature`.
+1. The full commit hash of your commit.
+
+Call `dpkg-buildpackage` as follows:
+
+```console
+dpkg-buildpackage -S \
+    $your_options \
+    --changes-option=-DVcs-Git=$repourl \
+    --changes-option=-DVcs-Git-Ref=$gitref \
+    --changes-option=-DVcs-Git-Commit=$commithash
+```
+
+Upload as usual:
+
+```console
+dput ubuntu ../<package>_<version>_source.changes
+```
+
+
+## Mangle workflow
+
+These instructions make the following assumptions:
+
+1. You have already built your source package and have the changes file ready
+   to upload, except that it doesn't contain a rich history reference.
+1. You have a local branch checked out, the checkout is identical to the source
+   package you have prepared, and your working directory is clean.
+1. A previous git-ubuntu commit is an ancestor of your current commit.
+1. You are at the top level of your source tree that is already built.
+
+Push your branch, adjust your changes file, re-sign it and upload as follows::
+
+```console
+git ubuntu prepare-upload mangle ../<package>_<version>_source.changes
+debsign ../<package>_<version>_source.changes
+dput ubuntu ../<package>_<version>_source.changes
+```
+
+`git ubuntu prepare-upload mangle` will push your branch to your
+namespace on Launchpad with the same remote branch name, and then modify your
+changes file to add the appropriate reference to the rich history, stripping
+out the now-invalidated signature if it was present. See
+{ref}`changes-file-headers`.