From 4a2fb18cdd104ef896faf522ed1386dfe948b0d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Kr=C3=A1tk=C3=BD?= Date: Fri, 10 Oct 2025 12:48:33 +0200 Subject: [PATCH 1/6] Add CSS class for soft-wrapping code/text blocks * Adds 'codeblock-wrap' custom CSS class * Adds requisite conf.py setting * Adds corresponding blurb in 'How to contribute docs' --- docs/.sphinx/_static/custom_styles.css | 1 + docs/conf.py | 2 +- docs/contributors/contribute-docs.md | 40 ++++++++++++++++++++++---- 3 files changed, 36 insertions(+), 7 deletions(-) create mode 100644 docs/.sphinx/_static/custom_styles.css diff --git a/docs/.sphinx/_static/custom_styles.css b/docs/.sphinx/_static/custom_styles.css new file mode 100644 index 00000000..70695785 --- /dev/null +++ b/docs/.sphinx/_static/custom_styles.css @@ -0,0 +1 @@ +.codeblock-wrap pre { white-space:pre-wrap; } diff --git a/docs/conf.py b/docs/conf.py index 20e0486f..7cf4a074 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -172,7 +172,7 @@ # Template and asset locations -# html_static_path = [".sphinx/_static"] +html_static_path = [".sphinx/_static"] # templates_path = [".sphinx/_static/_templates"] diff --git a/docs/contributors/contribute-docs.md b/docs/contributors/contribute-docs.md index 57beb4e9..b24c55b1 100644 --- a/docs/contributors/contribute-docs.md +++ b/docs/contributors/contribute-docs.md @@ -426,21 +426,49 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit ```` +### Code blocks + +To show a snippet of source code, use a literal block with the required language for syntax highlighting. For example: + +````md +```python +# "Hello, world!" script + +print('Hello, world!') +``` +```` + +Use `none` as the language to prevent any syntax highlighting. + + +### Unformatted text with soft wrap + +To show a text block with soft line-wrapping that interprets no mark-up formatting and uses a monospace font (e.g. for sample email or comment messages), use the `code` directive with the custom `codeblock-wrap` CSS class. For example: + +````{code} md +:class: codeblock-wrap + +```{code} +:class: codeblock-wrap + +_Lorem_ ipsum **dolor** sit amet, [consectetur](adipiscing.elit). Sed lobortis nec mauris ac placerat. Cras pulvinar dolor at orci semper hendrerit. Nam elementum leo vitae quam commodo, blandit ultricies diam malesuada. Suspendisse lacinia euismod quam interdum mollis. Pellentesque a eleifend ante. + +Aliquam tempus ultricies velit, eget consequat magna volutpat vitae. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Mauris pulvinar vestibulum congue. Aliquam et magna ultrices justo condimentum varius. +``` +```` + + ## Testing the documentation Test your changes before submitting a pull request. Run the following commands from within the `docs/` directory to test the documentation locally: | command | use | |---------|-----| -| `make spelling` | Check for spelling errors; this command checks the HTML files in the `_build` directory. Fix any errors in the corresponding Markdown file | -| `make linkcheck` | Check for broken links | +| `make spelling` | Check for spelling errors | +| `make linkcheck` | Check for broken links | | `make woke` | Check for non-inclusive language | | `make pa11y` | Check for accessibility issues | -:::{note} -For the `make spelling` command to work, you must have the `aspell` spellchecker installed. You can install it with `sudo apt install aspell`. -::: - ## Open Documentation Academy From a5349270f50b9701661134ebb3b792aeb6c0d431 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Kr=C3=A1tk=C3=BD?= Date: Fri, 10 Oct 2025 12:51:03 +0200 Subject: [PATCH 2/6] Update bug responses to soft-wrap comment samples --- docs/contributors/bug-triage/bug-responses.md | 225 +++++++++++++----- 1 file changed, 168 insertions(+), 57 deletions(-) diff --git a/docs/contributors/bug-triage/bug-responses.md b/docs/contributors/bug-triage/bug-responses.md index 9bdff6e5..3e7ebaff 100644 --- a/docs/contributors/bug-triage/bug-responses.md +++ b/docs/contributors/bug-triage/bug-responses.md @@ -22,7 +22,9 @@ Only members of `bug-control` can commit to this branch, but even if you are not ### Not described well -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. Unfortunately, we cannot work on this bug because your description didn't include enough information. You may find it helpful to read "How to report bugs effectively" http://www.chiark.greenend.org.uk/~sgtatham/bugs.html. We'd be grateful if you would then provide a more complete description of the problem. We have instructions on debugging some types of problems at http://wiki.ubuntu.com/DebuggingProcedures. @@ -41,7 +43,9 @@ Thank you! ### Missing steps to recreate bug -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. Please answer these questions: * Is this reproducible? @@ -53,7 +57,9 @@ This will help us to find and resolve the problem. ### Missing Apport information -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. Please execute the following command only once, as it will automatically gather debugging information, in a terminal: apport-collect BUGNUMBER @@ -74,7 +80,9 @@ Pleas also see the Ubuntu Kernel Team's [specific responses](https://wiki.ubuntu ### Debugging sound problems -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. We need some more information from you before we can start working on this bug. Please include the information requested from the "Reporting Sound Bugs" section of https://wiki.ubuntu.com/DebuggingSoundProblems as separate attachments. @@ -89,7 +97,9 @@ where BUGNUMBER is the number of the bug you've reported. ### Debugging ACPI -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. We need some more information from you before we can start working on this bug. Please include the information requested at https://wiki.ubuntu.com/DebuggingACPI as separate attachments. @@ -98,7 +108,9 @@ Please include the information requested at https://wiki.ubuntu.com/DebuggingACP ### Debugging Removable Devices -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. We need some more information from you before we can start working on this bug. Please include the information requested at https://wiki.ubuntu.com/DebuggingRemovableDevices as separate attachments. @@ -107,7 +119,9 @@ Please include the information requested at https://wiki.ubuntu.com/DebuggingRem ### Debugging Printing problems -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. We need some more information from you before we can start working on this bug. Please include the information requested at https://wiki.ubuntu.com/DebuggingPrintingProblems as separate attachments. @@ -116,7 +130,9 @@ Please include the information requested at https://wiki.ubuntu.com/DebuggingPri ### Debugging Hardware Detection -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. We need some more information from you before we can start working on this bug. Please include the information requested at https://wiki.ubuntu.com/DebuggingHardwareDetection as separate attachments. @@ -125,7 +141,9 @@ Please include the information requested at https://wiki.ubuntu.com/DebuggingHar ### Debugging USB Storage -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. We need some more information from you before we can start working on this bug. Please include the information requested at https://help.ubuntu.com/community/DebuggingUSBStorage as separate attachments. @@ -134,7 +152,9 @@ Please include the information requested at https://help.ubuntu.com/community/De ### Debugging Xorg in general -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. In order to attach necessary information for debugging this as an Xorg problem please run the following command only once: apport-collect BUGNUMBER @@ -145,7 +165,9 @@ Please ensure you have xdiagnose installed, and that you click the Yes button fo ### Freeze during boot or shutdown screen -```none +```{code} none +:class: codeblock-wrap + Thanks for your bug report and for your contribution to Ubuntu. In order to determine if this issue is plymouth related, please boot your computer with plymouth disabled and then shutdown to see if you can reproduce the issue. To disable plymouth for a single boot, follow these steps: 1. Hold Right-Shift during Grub boot delay to access the boot menu. @@ -157,7 +179,9 @@ Thanks for your bug report and for your contribution to Ubuntu. In order to dete ### Debugging Plymouth -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. Please run the following command only once via a terminal: apport-collect BUGNUMBER @@ -168,7 +192,9 @@ which will attach necessary information for debugging this as a plymouth problem ### Debugging Live Installation -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. Unfortunately we can't start working on it yet, because your description didn't include enough information. Please execute the following command 'ubuntu-bug ubiquity' as it will gather detailed information regarding your installation. Thanks in advance. @@ -179,14 +205,18 @@ Please execute the following command 'ubuntu-bug ubiquity' as it will gather det [Debugging Update Manager](https://wiki.ubuntu.com/DebuggingUpdateManager) -```none +```{code} none +:class: codeblock-wrap + Thanks for taking the time to report this bug and helping to make Ubuntu better. Could you please add the log files from '/var/log/dist-upgrade/' to this bug report as separate attachments? Thanks in advance. ``` ### Debugging GNOME Power Manager -```none +```{code} none +:class: codeblock-wrap + Thanks for taking the time to report this bug and helping to make Ubuntu better. Could you please run the following command only once in a terminal: apport-collect BUGNUMBER @@ -203,7 +233,9 @@ Apport will add the output of the upstream script `gnome-power-bugreport.sh` and If a Network Manager bug report is about not being able to connect, the title or summary should be in the format: `[CHIPSET] cannot connect to (ENCRYPT_METHOD)` where `CHIPSET` is the wireless driver used and `ENCRYPT_METHOD` is the encryption method used by your wireless network. -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. Unfortunately we can't start working on it yet, because your bug report didn't include enough information. Please include the information requested at https://wiki.ubuntu.com/DebuggingNetworkManager If you have trouble, do not hesitate to ask for more assistance. Thanks in advance. @@ -212,7 +244,9 @@ Please include the information requested at https://wiki.ubuntu.com/DebuggingNet ### Debugging Firefox -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. Could you please try to obtain a backtrace by following the instructions on https://wiki.ubuntu.com/MozillaTeam/Bugs? Also, please answer these questions: Is this crash reproducible? If so, which are the steps that lead to it? @@ -228,7 +262,9 @@ This will greatly aid us in tracking down your problem. Firefox bug triaging policy is to close (set to *Invalid*) crash reports from Apport that fail retracing. -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. However, your crash report didn't yield the required information. Please go ahead and submit a new crash report if it crashes again with the latest available version of the package. Thanks in advance for your cooperation and understanding. ``` @@ -247,7 +283,9 @@ Please see the [debugging OpenLDAP](https://wiki.ubuntu.com/DebuggingOpenldap) a Mostly `libavcodec` and `libavformat` bugs. -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. You have reported a crash that actually happened in the libavcodec or libavformat library. In order to be able to actually fix this bug, we must be able to: 1. Reproduce it; @@ -262,7 +300,9 @@ Please also make sure that your file crashes with the commandline application "f ### Debugging SCIM-related issues -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. In order to determine the cause of this issue, we would need some additional information. Please post or attach the following: @@ -296,11 +336,12 @@ This is not the best place for the bug though and we should encourage bug report Keep in mind `PKGNAME` is a placeholder. ```{warning} - If you use this response, you must assign a package. If you do not know what package to assign, please leave the bug alone, and ask for help. ``` -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. This bug did not have a package associated with it, which is important for ensuring that it gets looked at by the proper developers. You can learn more about finding the right package at https://wiki.ubuntu.com/Bugs/FindRightPackage. I have classified this bug as a bug in PKGNAME. When reporting bugs in the future please use apport by using 'ubuntu-bug' and the name of the package affected. You can learn more about this functionality at https://help.ubuntu.com/community/ReportingBugs. @@ -313,7 +354,9 @@ Occasionally, bug reporters will indicate that a bug has been fixed after some s These bug reports should be set to *Invalid* since we don't know the root cause. When closing the bug report it is a good idea to take an opportunity to let the reporter know how to manage bug statuses. -```none +```{code} none +:class: codeblock-wrap + This bug report is being closed due to your last comment regarding this being fixed with an update. For future reference you can manage the status of your own bugs by clicking on the current status in the yellow line and then choosing a new status in the revealed drop down box. You can learn more about bug statuses at https://wiki.ubuntu.com/Bugs/Status. Thank you again for taking the time to report this bug and helping to make Ubuntu better. Please submit any future bugs you may find. ``` @@ -327,14 +370,18 @@ Before using this, *please* check `rmadison ` to see if the package ver If it has not changed, there is no need to ask. If it has changed, check the changelog (via `aptitude changelog $PKGNAME`) to see if this issue has been specifically addressed. -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. The issue that you reported is one that should be reproducible with the live environment of the Desktop ISO of the development release. It would help us greatly if you could test with it so we can work on getting it fixed in the next release of Ubuntu. You can find out more about the development release at http://www.ubuntu.com/testing/. Thanks again and we appreciate your help. ``` ## Missing a crash report or having a .crash attachment -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. It sounds like some part of the system has crashed. To help us find the cause of the crash please follow these steps: 1. Run these commands: @@ -357,21 +404,27 @@ Please take care to avoid attaching .crash files to bugs as we are unable to pro When making a bug report a duplicate of another it is important to communicate to the reporter that any discussion regarding the bug should take place in the primary bug. Keep in mind that NUMBER is a placeholder and should be the number of the primary bug report. -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. This particular bug has already been reported and is a duplicate of bug NUMBER, so it is being marked as such. Please look at the other bug report to see if there is any missing information that you can provide, or to see if there is a workaround for the bug. Additionally, any further discussion regarding the bug should occur in the other report. Feel free to continue to report any other bugs you may find. ``` ## About an obsolete version of the software for reporter's release -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. However, according to this report, you are not using the most recent version of this package for your Ubuntu release. Please upgrade to the most recent version and let us know if you are still having this issue. Thanks in advance. ``` ## Missing a backtrace -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. Please try to obtain a backtrace following the instructions at http://wiki.ubuntu.com/DebuggingProgramCrash and upload the backtrace (as an attachment) to the bug report. This will greatly help us in tracking down your problem. ``` @@ -382,7 +435,9 @@ This is an alternative to the previous response, if there is a good chance that another retrace will work better (e.g. outdated package versions). Please close the bug as *Invalid* with this comment: -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. However, processing it in order to get sufficient information for the developers failed (it does not generate an useful symbolic stack trace). This might be caused by some outdated packages which were installed on your system at the time of the report. Please upgrade your system to the latest package versions. If you still encounter the crash, please file a new report. @@ -393,7 +448,9 @@ Thank you for your understanding, and sorry for the inconvenience! ## Need valgrind log -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. Please try to obtain a valgrind log following the instructions at https://wiki.ubuntu.com/Valgrind and attach the file to the bug report. This will greatly help us in tracking down your problem. ``` @@ -403,20 +460,26 @@ Thank you for taking the time to report this bug and helping to make Ubuntu bett If you are sure the reported bug is not caused by the packaging for Ubuntu, it should usually be sent upstream by someone affected by the bug. If appropriate, replace GNOME with the organization behind the software (see [the upstream wiki page](https://wiki.ubuntu.com/Bugs/Upstream/) for available organizations): -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. The issue you are reporting is an upstream one and it would be nice if somebody having it could send the bug to the developers of the software by following the instructions at https://wiki.ubuntu.com/Bugs/Upstream/GNOME. If you have done so, please tell us the number of the upstream bug (or the link), so we can add a bugwatch that will inform us about its status. Thanks in advance. ``` If you have already pointed out that the reported bug is an upstream one, but there hasn't been any feedback about the requested upstream bug for 2 weeks, the reporter (or someone else affected by the bug) might have forgotten it. If that's the case, you should ask if someone has already forwarded the bug upstream and can tell you the number of the upstream bug: -```none +```{code} none +:class: codeblock-wrap + Is there any news about this bug? Has someone affected by this bug sent the report upstream? Could you tell us the bug number, so we can add a bugwatch that will inform us about its status? Thanks in advance. ``` However, if you have already sent the bug upstream, you should leave a comment stating where the upstream bug can be found: -```none +```{code} none +:class: codeblock-wrap + Thank you for your bug report. This bug has been reported to the developers of the software. You can track it and make comments at: ``` @@ -425,7 +488,9 @@ Thank you for your bug report. This bug has been reported to the developers of t Old new bugs that haven't been touched in a quite a while and you are unable to recreate the bug. -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. We are sorry that we do not always have the capacity to look at all reported bugs in a timely manner. There have been many changes in Ubuntu since that time you reported the bug and your problem may have been fixed with some of the updates. It would help us a lot if you could test it on a currently supported Ubuntu version. When you test it and it is still an issue, kindly upload the updated logs by running only once: apport-collect @@ -439,7 +504,9 @@ and any other logs that are relevant for this particular issue. Occasionally, bug reporters will report a bug about a version of a package not provided by Ubuntu or (less often) about software not provided by Ubuntu. In this case we can not help them and the bug should be set to *Invalid*. -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and trying to help make Ubuntu better. However, it seems that you are not using a software package provided by the official Ubuntu repositories. Because of this the Ubuntu project can not support or fix your particular bug. Please report this bug to the provider of the software package. Thanks! If you are interested in learning more about software repositories and Ubuntu, check https://help.ubuntu.com/community/Repositories. @@ -450,7 +517,9 @@ If you are interested in learning more about software repositories and Ubuntu, c The bug's state should become *Fix Released* and if the package qualifies for a [Stable Release Update (SRU)](https://documentation.ubuntu.com/sru/en/latest/): -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. However, I am closing it because the bug has been fixed in the latest development version of Ubuntu. This is a significant bug in Ubuntu. If you need a fix for the bug in previous versions of Ubuntu, please perform as much as possible of the SRU Procedure [1] to bring the need to a developer's attention. @@ -460,7 +529,9 @@ This is a significant bug in Ubuntu. If you need a fix for the bug in previous v The bug's state should become *Fix Released* and if the package does not qualify for an SRU because it is considered a minor bug and the package can be backported: -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. However, I am closing it because the bug has been fixed in the latest development version of Ubuntu. If you need a fix for the bug in previous versions of Ubuntu, please follow the instructions for "Requesting a Backport" at https://wiki.ubuntu.com/UbuntuBackports#Requesting_a_Backport. @@ -468,14 +539,18 @@ If you need a fix for the bug in previous versions of Ubuntu, please follow the The bug's state should become *Fix Released* and if the package can not be backported: -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. However, I am closing it because the bug has been fixed in the latest development version of Ubuntu. It won't be fixed in previous versions of Ubuntu because the package doesn't fit the requirements for backporting. See https://wiki.ubuntu.com/UbuntuBackports for more information. ``` ## Reported by someone not respecting the Code of Conduct -```none +```{code} none +:class: codeblock-wrap + Thank you for your bug report. To maintain a respectful atmosphere, please follow the code of conduct - http://www.ubuntu.com/project/about-ubuntu/conduct. Bug reports are handled by humans, the majority of whom are volunteers, so please bear this in mind. ``` @@ -484,13 +559,17 @@ Thank you for your bug report. To maintain a respectful atmosphere, please follo Determining whether a bug report is actually a support request can be quite challenging, but if you decide the bug *is* a support request you can convert it to such by clicking {guilabel}`Convert to a question` at the top of the bug's web page. This will mark the bug as *Invalid*, create a new question in the answer tracker and link it to the bug. In the comment dialog that you receive, post a comment to inform the reporter about your action, and advise them to use the support tracker for any future problems. -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this issue and helping to make Ubuntu better. Examining the information you have given us, this does not appear to be a bug report so we are closing it and converting it to a question in the support tracker. We understand the difficulties you are facing, but it is better to raise problems you are having in the support tracker at https://answers.launchpad.net/ubuntu if you are uncertain if they are bugs. If you would prefer live chat support, you can find an IRC support channel for your flavor of Ubuntu here: https://wiki.ubuntu.com/IRC/ChannelList. You can also find help with your problem in the support forum of your local Ubuntu community http://loco.ubuntu.com/ or asking at https://askubuntu.com or https://discourse.ubuntu.com/t/welcome-to-support-and-help/49951. For help on reporting bugs, see https://help.ubuntu.com/community/ReportingBugs. ``` Chris Guiver provides an alternate wording (thanks, Chris!): -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. Bug reporting is about finding & fixing problems thus preventing future users from hitting the same bug. @@ -505,7 +584,9 @@ It is also a good idea to change the source package beforehand if it's set incor This response is appropriate when a bug is not reported in English or some error messages are not in English. -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this issue and helping to make Ubuntu better. We noticed that some of the sentences in this bug report are not in English. If they were translated to English they would be more understandable to triagers. Could you please translate them? ``` @@ -514,7 +595,9 @@ Thank you for taking the time to report this issue and helping to make Ubuntu be This response may be necessary when someone is having strange issues with the Desktop ISO. -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. While we appreciate the difficulties you are facing, it would appear that the image (ISO file) you downloaded could be corrupt. There is an easy way to verify the integrity of the Ubuntu ISO files you download. Could you please visit https://help.ubuntu.com/community/HowToMD5SUM follow the instructions and report back as to whether or not the MD5SUM verified? Thanks in advance. ``` @@ -523,35 +606,45 @@ Thank you for taking the time to report this bug and helping to make Ubuntu bett This should only be used for bug reports where the scope of the change is quite large or would affect a lot of users. -```none +```{code} none +:class: codeblock-wrap + Thank you for your suggestion. However, the changes you are requesting aren't really a bug and require more discussion, which should be done on an appropriate mailing list or forum. http://www.ubuntu.com/support/community/mailinglists might be a good start for determining which mailing list to use. ``` ## About an incorrect translation -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. Translations in Ubuntu are handled by the Ubuntu Translations project at https://launchpad.net/ubuntu-translations, so we are going to move this bug report over to that project. ``` ## Incomplete package request -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to request this package and helping to make Ubuntu better. Unfortunately you have not provided enough information for a developer to start packaging this application. Please make sure this bug meets the guidelines at https://wiki.ubuntu.com/UbuntuDevelopment/NewPackages. An example of a complete package request is available at https://wiki.ubuntu.com/UbuntuDevelopment/NewPackages/ExamplePackageRequest). ``` ## Triage successful -```none +```{code} none +:class: codeblock-wrap + Thanks for reporting this bug and any supporting documentation. Since this bug has enough information provided for a developer to begin work, I'm going to mark it as confirmed and let them handle it from here. Thanks for taking the time to make Ubuntu better! ``` ## Triage unsuccessful: Back to New/Incomplete Status -```none +```{code} none +:class: codeblock-wrap + Thanks for taking the time to report this bug and comment on it. However, I've noticed that this bug has been Confirmed although there is not clear indication as to how to recreate this bug [or version of software affected]. Subsequently, I'm setting its status to Incomplete until that information is provided. You can learn more about bug statuses at http://wiki.ubuntu.com/Bugs/Status. Thanks for taking the time to make Ubuntu better! ``` @@ -560,7 +653,9 @@ Thanks for taking the time to report this bug and comment on it. However, I've n If the specific release has reached End of Life (as per {ref}`list-of-releases` and there is not enough information to work on the bug, then you can set to *Incomplete* and use the following response (delete the lines that are not relevant): -```none +```{code} none +:class: codeblock-wrap + Thank you for reporting this bug to Ubuntu. Ubuntu 24.10 (oracular) reached end-of-life on July 10, 2025 @@ -610,7 +705,9 @@ We appreciate that this bug may be old and you might not be interested in discus When reviewing bug attachments you might find an attachment [that is a patch](https://wiki.ubuntu.com/Bugs/Patches), but is not flagged. Let people know what a patch is! -```none +```{code} none +:class: codeblock-wrap + Looking at the attachments in this bug report, I noticed that an attachment was not flagged as a patch. A patch contains changes to an Ubuntu package that will resolve a bug and this attachment is one! Subsequently, I've checked the patch flag for it. In the future when submitting patches please use the patch checkbox as there are some Launchpad searches that use this feature. You can learn more about the patch workflow at https://wiki.ubuntu.com/Bugs/Patches. ``` @@ -619,7 +716,9 @@ Looking at the attachments in this bug report, I noticed that an attachment was When reviewing bug attachments you might that someone flagged an attachment [that is a patch](https://wiki.ubuntu.com/Bugs/Patches), but it really isn't one. Let people know what a patch is! -```none +```{code} none +:class: codeblock-wrap + Looking at the attachments in this bug report, I noticed that one was flagged as a patch incorrectly. A patch contains changes to an Ubuntu package that will resolve a bug, since this was not one I've unchecked the patch flag for it. In the future keep in mind the definition of a patch. You can learn more about what qualifies as a patch at https://wiki.ubuntu.com/Bugs/Patches. Thanks! ``` @@ -628,7 +727,9 @@ Looking at the attachments in this bug report, I noticed that one was flagged as If the problem looks like local file system corruption (e.g. {lpbug}`322714`), which indicates broken/truncated `dpkg .list` files), it is most likely not something we can fix in Ubuntu in general. Since we have a large number of such bugs, it is probably best to close it as *Invalid* (or *Incomplete* if you want to follow-up and subscribe) with this comment: -```none +```{code} none +:class: codeblock-wrap + Thank you for your report. This package failure looks like being caused by a corrupted file system. Please start the "Memory check" from the boot menu. If that runs successfully, please start the desktop ISO. Hold right-shift key after the BIOS checks to get to the grub menu and run "Check disc for errors" option. If the file system corruption is serious, the safest option would be to reinstall your system. ``` @@ -640,21 +741,27 @@ Please see the Ubuntu Security Team's [bug triage](https://wiki.ubuntu.com/Secur ## Added bug watch -```none +```{code} none +:class: codeblock-wrap + Thanks for taking the time to report this bug in the upstream bug tracking system this is a tremendous help. Launchpad has the ability to watch lots of upstream bug trackers and this can be done by following the procedure documented at https://wiki.ubuntu.com/Bugs/Watches. I've added the bug watch for this bug report. ``` ## Hanging application or daemon -```none +```{code} none +:class: codeblock-wrap + Thanks for your interest in helping to resolve this issue. In order to get to the bottom of this we need to figure out where the program is hanging. If you can follow the steps on https://wiki.ubuntu.com/Backtrace#Already_running_programs and attach the generated text file to this bug it would be of great help. ``` ## User incorrectly subscribing a team to a bug -```none +```{code} none +:class: codeblock-wrap + Thanks for your interest in helping to resolve this issue. There is no need to subscribe anyone to this bug, as it generates unnecessary emails and will not resolve the issue any faster. Your bug will be looked at by a developer as time permits. ``` @@ -663,7 +770,9 @@ Thanks for your interest in helping to resolve this issue. There is no need to s Beginning in Ubuntu 22.04, Firefox is provided as a snap created and published directly by Mozilla. Users, however, can still report against the Firefox package directly in Launchpad. Apport still warns against this, but Launchpad does not. Add this comment (a slight modification of the response from Apport) if the bug mentions occurring in 22.04 (or later) and mark the bug as *Incomplete*. If the user mentions the package as not being a snap, then it's *Invalid* as it came from a source other than Ubuntu or the snap. -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and help make Ubuntu better. Firefox is provided by a snap published by Mozilla, and they may not be aware of this issue. Please contact them via https://support.mozilla.org/kb/file-bug-report-or-feature-request-mozilla and link the bug report here so it can be further tracked. Thank you! ``` @@ -672,7 +781,9 @@ Thank you for taking the time to report this bug and help make Ubuntu better. Fi Sometimes we receive bug reports from unofficial derivatives (such as Linux Mint), which we cannot guarantee bugs can be fixed for or can support, so they need to be closed as *Invalid* with this message: -```none +```{code} none +:class: codeblock-wrap + Thank you for taking the time to report this bug and helping to make Ubuntu better. However, per your report, it seems as though you are not actually running Ubuntu but a derivative distribution. Derivatives are not official flavours and may have additional repositories that provide packages that conflict with our official packages, so we cannot provide support or debug when things go wrong in these distributions. Official flavours of Ubuntu are listed here: https://ubuntu.com/desktop/flavours From 9d826bb23593deb35fe4f413e7e599af0ab8b4e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Kr=C3=A1tk=C3=BD?= Date: Sat, 11 Oct 2025 20:38:16 +0200 Subject: [PATCH 3/6] Add git-ubuntu docs from git-ubuntu's LP repo * Articles consolidated to group very short ones * Topics split based on 'explanation' vs 'howto': - How Ubuntu is made -> Processes: explanations, reference - Contributors -> Advanced: howtos for uploaders * Minor topics incorporated into existing articles * Article on testing git-ubuntu left out * Created 'Contributors -> Uploading' section * Redirects added as needed to 'Uploading' * Removed Intersphinx mapping to git-ubuntu docs --- docs/conf.py | 4 - .../advanced/handle-git-ubuntu-uploads.md | 245 ++++++++++++++++++ docs/contributors/advanced/index.md | 4 +- .../advanced/sponsor-an-upload.md | 4 +- .../advanced/upload-with-rich-history.md | 99 +++++++ docs/contributors/index.md | 18 +- docs/contributors/merging/merge-process.md | 4 +- .../setup/set-up-for-ubuntu-development.md | 14 + .../{ => uploading}/find-a-sponsor.md | 0 docs/contributors/uploading/index.md | 17 ++ .../{ => uploading}/request-a-sync.md | 0 .../{ => uploading}/request-an-upload.md | 0 .../git-ubuntu/changes-file-headers.md | 21 ++ .../processes/git-ubuntu/empty-directories.md | 45 ++++ ...git-ubuntu-design-goals-and-principles.rst | 143 ++++++++++ .../processes/git-ubuntu/index.md | 113 ++++++++ docs/how-ubuntu-is-made/processes/index.md | 18 +- docs/redirects.txt | 4 +- 18 files changed, 732 insertions(+), 21 deletions(-) create mode 100644 docs/contributors/advanced/handle-git-ubuntu-uploads.md create mode 100644 docs/contributors/advanced/upload-with-rich-history.md rename docs/contributors/{ => uploading}/find-a-sponsor.md (100%) create mode 100644 docs/contributors/uploading/index.md rename docs/contributors/{ => uploading}/request-a-sync.md (100%) rename docs/contributors/{ => uploading}/request-an-upload.md (100%) create mode 100644 docs/how-ubuntu-is-made/processes/git-ubuntu/changes-file-headers.md create mode 100644 docs/how-ubuntu-is-made/processes/git-ubuntu/empty-directories.md create mode 100644 docs/how-ubuntu-is-made/processes/git-ubuntu/git-ubuntu-design-goals-and-principles.rst create mode 100644 docs/how-ubuntu-is-made/processes/git-ubuntu/index.md diff --git a/docs/conf.py b/docs/conf.py index 7cf4a074..b06f1622 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -402,10 +402,6 @@ None, ), "sru": ("https://canonical-sru-docs.readthedocs-hosted.com/en/latest/", None), - "git-ubuntu": ( - "https://canonical-git-ubuntu.readthedocs-hosted.com/en/latest/", - None, - ), } diff --git a/docs/contributors/advanced/handle-git-ubuntu-uploads.md b/docs/contributors/advanced/handle-git-ubuntu-uploads.md new file mode 100644 index 00000000..f2c7ce95 --- /dev/null +++ b/docs/contributors/advanced/handle-git-ubuntu-uploads.md @@ -0,0 +1,245 @@ +(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 + +```none +$ git ubuntu clone [dir-name] +``` + +For example, for a contribution to dovecot, you might run: + +```none +$ git ubuntu clone dovecot dovecot-gu +``` + + +## Add remote tracking branches to a git-ubuntu checkout + +In order to review the sponsoree's changes, you'll want to add their +Launchpad username to your local checkout: + +```none +$ git ubuntu remote add +$ git checkout "/" -b "" +``` + + +## 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: + +```none +$ 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: + +```none +$ git checkout pkg/ubuntu/jammy-devel -b 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. + +```none +$ mkdir review-lp +$ cd review-lp +$ wget +$ git ubuntu clone -gu +$ cd -gu +$ git checkout pkg/ubuntu/-devel -b review-lp- +$ debdiff-apply < ../ +$ git commit debian/changelog -m changelog +$ changes=$(dpkg-parsechangelog -S Changes | grep "^ ") +$ update-maintainer -r +Restoring original maintainer: ... +$ git commit -a -m "${changes}" +$ 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, you can proceed with reviewing and building using the +techniques described elsewhere. + +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 `. 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: + +```none +$ git ubuntu clone apache2 +$ cd apache2 +$ git tag -f base + +$ git-ubuntu.experimental-emptydirfixup fix-many base +$ dpkg-buildpackage $(git ubuntu prepare-upload args) -S +``` + + +## Build a git-ubuntu source package branch for uploading + +Assuming you have the branch checked out that you want to build, and are +running inside an Ubuntu release matching the MP's release (e.g. in an +LXC container), here is one way to build the source package from the +branch: + +```none +$ install-build-deps +$ git ubuntu export-orig [--for-merge] +$ upload_args=$(git ubuntu prepare-upload args) +$ debuild --no-lintian -S -uc -us ${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. + +The `install-build-deps` script can be found in the ubuntu-helpers repository, or +you can download it directly from [install-build-deps](https://git.launchpad.net/~ubuntu-server/+git/ubuntu-helpers/plain/bryce/install-build-deps). + +This calculates the build requirements using the debian/control file in +the current directory tree. This is more reliable than using +`apt-get build-dep ` when the changes you're reviewing have +some package dependency changes, such as when merging a new upstream +package. + + +## Run autopkgtests against a git-ubuntu branch + +Here's a workflow snippet to toss the changes into a PPA and run tests +on that: + +```none +$ ppa="ppa:/-review-lp" +$ ppa create ${ppa} +$ dput ${ppa} +$ ppa wait ${ppa} +$ ppa tests ${ppa} +``` + +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/` to see when + git-ubuntu last updated the package repository. +1. Check `https://launchpad.net/ubuntu/+source//+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. diff --git a/docs/contributors/advanced/index.md b/docs/contributors/advanced/index.md index 0d2f261f..4089df79 100644 --- a/docs/contributors/advanced/index.md +++ b/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 +Upload with rich history Review a merge proposal Sponsor an upload Sponsor a sync diff --git a/docs/contributors/advanced/sponsor-an-upload.md b/docs/contributors/advanced/sponsor-an-upload.md index bf647376..10c74891 100644 --- a/docs/contributors/advanced/sponsor-an-upload.md +++ b/docs/contributors/advanced/sponsor-an-upload.md @@ -29,7 +29,7 @@ If you are interested in {ref}`sponsoring `, 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` diff --git a/docs/contributors/advanced/upload-with-rich-history.md b/docs/contributors/advanced/upload-with-rich-history.md new file mode 100644 index 00000000..6408f8cf --- /dev/null +++ b/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 ` 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: + +```none +$ dpkg-buildpackage $(git ubuntu prepare-upload args) -S +$ dput ubuntu ../__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: + +```none +$ dpkg-buildpackage -S \ + --changes-option=-DVcs-Git= \ + --changes-option=-DVcs-Git-Ref= \ + --changes-option=-DVcs-Git-Commit= \ + +``` + +Upload as usual: + +```none +$ dput ubuntu ../__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:: + +```none +$ git ubuntu prepare-upload mangle ../__source.changes +$ debsign ../__source.changes +$ dput ubuntu ../__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`. diff --git a/docs/contributors/index.md b/docs/contributors/index.md index b0c09fa7..e75c9672 100644 --- a/docs/contributors/index.md +++ b/docs/contributors/index.md @@ -70,34 +70,32 @@ merging/index ``` -## New packages +## Uploading and sponsorship + +All aspects of seeking sponsorship for uploads to the Archive are covered in the {ref}`sponsorship` article series. ```{toctree} :maxdepth: 1 -new-package/index +Uploading ``` -## Accessibility +## New packages ```{toctree} :maxdepth: 1 -Check accessibility +new-package/index ``` -## Sponsorship - -All aspects of seeking sponsorship as well as being a sponsor are covered in the {ref}`sponsorship` article series. +## Accessibility ```{toctree} :maxdepth: 1 -Find a sponsor -Request an upload -Request a sync +Check accessibility ``` diff --git a/docs/contributors/merging/merge-process.md b/docs/contributors/merging/merge-process.md index 220a744d..446011a8 100644 --- a/docs/contributors/merging/merge-process.md +++ b/docs/contributors/merging/merge-process.md @@ -1,7 +1,7 @@ (merge-process)= # Merge process -Perform the merge using the {manpage}`git-ubuntu(1)` tool. See also the dedicated {external+git-ubuntu:doc}`git-ubuntu documentation `. +Perform the merge using the {manpage}`git-ubuntu(1)` tool. ::::{admonition} **Merging** series The article series provides guidance on performing package merges. @@ -75,7 +75,7 @@ These will silently disappear on commit, causing extraneous unintended changes. See: LP: #1687057. ``` -These empty directories can cause the rich history to become lost when uploading them to the Archive. When that happens, use {external:doc}`howto/restore-empty-directories`. +These empty directories can cause the rich history to become lost when uploading them to the Archive. When that happens, use {ref}`restore-empty-directories`. ::: diff --git a/docs/contributors/setup/set-up-for-ubuntu-development.md b/docs/contributors/setup/set-up-for-ubuntu-development.md index dfe7f85d..79c11a9e 100644 --- a/docs/contributors/setup/set-up-for-ubuntu-development.md +++ b/docs/contributors/setup/set-up-for-ubuntu-development.md @@ -99,6 +99,20 @@ so, create a new 4096-bit one and deprecate the old one in Launchpad, GitHub, etc. +(keyring-with-plaintext-storage)= +### Keyring with plaintext storage + +See {ref}`keyring-integration` for details on how `git-ubuntu` uses keyring. If +you want to reconfigure keyring to use plaintext storage to avoid getting +keyring password prompts, create the file +`~/.local/share/python_keyring/keyringrc.cfg` with the following contents: + +```none +[backend] +default-keyring=keyrings.alt.file.PlaintextKeyring +``` + + (git)= ### Git diff --git a/docs/contributors/find-a-sponsor.md b/docs/contributors/uploading/find-a-sponsor.md similarity index 100% rename from docs/contributors/find-a-sponsor.md rename to docs/contributors/uploading/find-a-sponsor.md diff --git a/docs/contributors/uploading/index.md b/docs/contributors/uploading/index.md new file mode 100644 index 00000000..f292cd7e --- /dev/null +++ b/docs/contributors/uploading/index.md @@ -0,0 +1,17 @@ +(uploading-to-the-archive)= +# Uploading to the Archive + +This section groups articles on how to have uploads to the Archive sponsored (for contributores without upload rights). The articles are part of the {ref}`sponsorship` series. + +```{toctree} +:maxdepth: 1 + +Find a sponsor +Request an upload +Request a sync +``` + +## Further reading + +* {ref}`how-to-handle-git-ubuntu-uploads` +* {ref}`package-archive` diff --git a/docs/contributors/request-a-sync.md b/docs/contributors/uploading/request-a-sync.md similarity index 100% rename from docs/contributors/request-a-sync.md rename to docs/contributors/uploading/request-a-sync.md diff --git a/docs/contributors/request-an-upload.md b/docs/contributors/uploading/request-an-upload.md similarity index 100% rename from docs/contributors/request-an-upload.md rename to docs/contributors/uploading/request-an-upload.md diff --git a/docs/how-ubuntu-is-made/processes/git-ubuntu/changes-file-headers.md b/docs/how-ubuntu-is-made/processes/git-ubuntu/changes-file-headers.md new file mode 100644 index 00000000..073b3051 --- /dev/null +++ b/docs/how-ubuntu-is-made/processes/git-ubuntu/changes-file-headers.md @@ -0,0 +1,21 @@ +(changes-file-headers)= +# Changes file headers + +git-ubuntu understands the following custom changes file headers: + +`Vcs-Git` +: Points to the git repository where the rich history can be found. + +`Vcs-Git-Ref` +: The ref which when fetched contains the rich history. + +`Vcs-Git-Commit` +: The commit hash of your rich history. This must match your upload. + +When git-ubuntu imports your upload, it will look in the location specified by +these headers for the rich history. If present and if they match your upload, +then it will use your commit instead of synthesizing its own. + +For now, only Launchpad git URLs are accepted to avoid the risk from a +malicious git repository host. `git-ubuntu prepare-upload` will check +that the URL will be acceptable. diff --git a/docs/how-ubuntu-is-made/processes/git-ubuntu/empty-directories.md b/docs/how-ubuntu-is-made/processes/git-ubuntu/empty-directories.md new file mode 100644 index 00000000..e4d2d4be --- /dev/null +++ b/docs/how-ubuntu-is-made/processes/git-ubuntu/empty-directories.md @@ -0,0 +1,45 @@ +(empty-directories)= +# Empty directories + +git's frontend doesn't let you add an empty directory. Usually the workaround +is to create any necessary empty directory at build time, or failing that to +create a placeholder file like `.empty` and check that in. + +Neither of these approaches work for git-ubuntu's importer in the general case. +A source package can ship an empty directory by nature of the source package +format. But the build system (ie. `debian/rules`) in the source package +expects the source exactly as packed. Just as some builds break if empty +directories are missing, other builds might break if empty directories are not +actually empty. + +Internally, git supports empty directories just fine. Directories map to git +tree objects. An empty tree object is the obvious way of representing an empty +directory, and git seems to accept them if they are represented this way. It's +just the git index and front end that do not support them. + +In git-ubuntu, we therefore import empty directories "correctly" and losslessly +by using empty tree objects as necessary. However when at the client end such a +tree is checked out, the empty directories disappear as they pass through the +index, and get lost. A subsequent commit made by a developer then gets created +from the index, so does not include the empty directories even if they haven't +been touched. + +This becomes an issue if a such a commit is subsequently presented back to +git-ubuntu as rich history to be adopted against an upload. git-ubuntu finds +that the upload (with empty directories) doesn't match the rich history commit +(with missing empty directories). + +```none +WARNING: empty directories exist but are not tracked by git: +These will silently disappear on commit, causing extraneous +unintended changes. See: LP: #1687057. +Use "git commit --no-verify ..." to ignore this problem. +``` + +Source packages can ship with empty directories, but git's frontend +doesn't allow adding empty directories. This can cause some confusion +for git ubuntu. For patch piloting this is worth being aware of, since +the workaround needs to be done at point of upload. + +For a full explanation and steps on how to handle it, see +{ref}`restore-empty-directories`. diff --git a/docs/how-ubuntu-is-made/processes/git-ubuntu/git-ubuntu-design-goals-and-principles.rst b/docs/how-ubuntu-is-made/processes/git-ubuntu/git-ubuntu-design-goals-and-principles.rst new file mode 100644 index 00000000..90407177 --- /dev/null +++ b/docs/how-ubuntu-is-made/processes/git-ubuntu/git-ubuntu-design-goals-and-principles.rst @@ -0,0 +1,143 @@ +.. _git-ubuntu-design-goals-and-principles: + +Git-ubuntu design goals and principles +====================================== + + +Consistency and tool unification +-------------------------------- + +One measure of success for git-ubuntu is to reduce or eliminate the occasions +where an experienced Ubuntu developer has to say "that package is special" when +a new developer or drive-by contributor is asking for help on performing a +routine task. + +Another measure is the amount of setup required before a developer can perform +a task, such as test building a package from a source tree in a reproducible +way. + +For example, in answer to the following questions, git-ubuntu already +eliminates the "this package is special" excuse for packages covered by +git-ubuntu repositories: + +* "Where can I clone the git tree for package X"? Without git-ubuntu, "this + package is special" is needed when a Vcs-Git header doesn't exist, or does + exist but no git branch is maintained for the Ubuntu delta, or does exist but + the header hasn't been updated to point to it. + +The following are medium term goals: + +* "How do I build package X"? Right now, the recommended :command:`sbuild` method + involves setting up :term:`chroots `, arranging :command:`sbuild` group membership, and :command:`sbuild` + default configuration expects an MTA that also requires setting up. + +* "How do I patch the version of package X that Ubuntu ships in release Y"? + Right now, this usually involves knowledge of quilt and the "3.0 (quilt)" + Debian source package format. + +Because git-ubuntu uses a single scheme to represent package source trees in +git, and also a single schema for all branch and tag names, automation that +operates on package sources is easier to write, including automation that needs +visibility across multiple package versions at once. For example, it's easier +to write automation to help validate SRUs since such automation can easily +inspect the current state of different releases and pockets. Instead of using +the Launchpad API for this kind of inspection, the tooling can inspect this +state using the same mechanism it can use to inspect the existing published +source tree and the source trees in Launchpad's queues. git is the single tool +that can be used for all of this. + +Single source of truth +---------------------- + +Uploads arrive into Ubuntu regardless of git-ubuntu, such as via syncs from +Debian or just direct uploads using ``dput`` without git-ubuntu. Launchpad is +the authority that publishes Ubuntu packages via apt. So Launchpad, not +git-ubuntu, is the authority and "single source of truth" of what the source +tree is for a particular package, and what they were historically. + +git-ubuntu is designed to be able to guarantee that its git repositories do +actually represent this single source of truth. Therefore, its git repositories +are necessarily derived from and form a view onto Launchpad's single source of +truth, and cannot define it. + +Integrity requirements +---------------------- + +Since git-ubuntu's git repositories are merely a view of Launchpad's single +source of truth, its refs (branches, tags, etc) must also be derived from that +truth and therefore must be read-only from the git perspective. Otherwise, +developers would be able to push a different truth to the git repositories that +do not reflect the truth in Launchpad, and that would defeat the purpose of +git-ubuntu in the first place. + +Similarly, the commits that correspond to specific published source package +versions must match what was uploaded exactly, so that developers can trust +that what they see in the git repository corresponds to what was actually +published. + +How uploads map to commits +-------------------------- + +In the common case, git-ubuntu achieves this by synthesizing a commit from what +was uploaded to Launchpad as a package upload. In this case, all the changes +from the previous upload are "squashed" into a single commit. + +However, the integrity requirement is just that the specific commits that +correspond to package uploads match. Intermediate commits are permitted, and +these need not be restricted for integrity purposes. + +Therefore, this schema allows for developers to provide a "richer" path that +describes how they arrived at their upload in more granular detail, in the +git usual way by providing intermediate commits. In git-ubuntu, since we aren't +the single source of truth, we must handle this specially to maintain our other +integrity requirements, and call this concept "rich history". + + +.. _rich-history: + +Rich history +------------ + +git-ubuntu's rich history mechanism has some requirements: + +#. The developer must provide rich history commits at the time of the dput-based (non-git) upload. + +#. These commits must remain available to the git-ubuntu importer until after it has imported them. + +#. The tree of the final rich history commit provided must precisely match the tree of the upload. There exist some edge cases necessary to maintain a lossless mapping from source package to git tree where git-ubuntu defines exactly what should happen to the tree; the rich history commit must do precisely the same to meet this requirement. + +#. The specification defines some further requirements; the general idea is that the rich history commits must be based on a commit that corresponds to a previous import and your upload must preserve the old ``debian/changelog`` entries in the usual way. + +If these requirements are met, then git-ubuntu will use your commits for its +import instead of synthesizing one. + +See :ref:`how-to-upload-with-rich-history` for instructions on providing rich history to the +importer. + + +Determining the parent +---------------------- + +Trust the uploader to base it correctly by looking at :file:`debian/changelog`. +This leads to "force pushes". + + +.. _keyring-integration: + +Keyring integration +------------------- + +Some git-ubuntu subcommands (e.g. ``git-ubuntu submit``) require authenticated +access to the Launchpad API. The first time you do this, you will be prompted +to authenticate in a web browser. If successful, the authenticated API key will +then be saved in your local keyring. You may be prompted for a password. This +password is used to encrypt your local keyring. If you don't yet have a local +keyring, the password you provide will be used to encrypt it. If you already +have a local keyring, the password you provide is the one required to decrypt +it. + +See :ref:`keyring-with-plaintext-storage` for instructions on configuring keyring to use +plaintext password storage instead, to avoid getting keyring password prompts. + +git-ubuntu uses `launchpadlib `_ for Launchpad API access. This +library in turn uses the `Python keyring package `_ for credential storage. If you see a password prompt, it is because the keyring package's defaults in your particular environment require encrypted password-based credential storage. Configure this to your needs by following the `keyring documentation `_. diff --git a/docs/how-ubuntu-is-made/processes/git-ubuntu/index.md b/docs/how-ubuntu-is-made/processes/git-ubuntu/index.md new file mode 100644 index 00000000..5591917c --- /dev/null +++ b/docs/how-ubuntu-is-made/processes/git-ubuntu/index.md @@ -0,0 +1,113 @@ +(git-ubuntu)= +# Git-ubuntu + +```{toctree} +:maxdepth: 1 +:hidden: + +Design goals and principles +changes-file-headers +empty-directories +``` + +As Ubuntu's packaging architecture pre-dates git, different packages have +evolved to use different mechanisms to achieve the same thing. Developers had +to learn them all in order to be effective when working across a wide range of +packages. git-ubuntu's unification of these mechanisms allows for simpler, more +general tooling, which results in faster onboarding of new developers and +easier "drive-by" contributions. + +git-ubuntu comprises two components: + +1. The git-ubuntu importer service runs the importer to maintain git +repositories of Ubuntu packages in Launchpad. + +1. The {command}`git-ubuntu` CLI tool contains all its provided automation for developer +use. + + +## Importer service + +The git-ubuntu importer service maintains a view of the entire packaging +version history of Ubuntu source packages using git repositories with a common +branching and tagging scheme. The git-ubuntu CLI provides tooling and +automation that understands these repositories to make the development of +Ubuntu itself easier. + + +### Sources only + +The git-ubuntu importer consumes source packages only, and has no involvement +with binaries. Launchpad's source and binary publication pipelines are +independent of each other, except that of course binary publications are +dependent on their corresponding source publications. So whether or not a build +fails, or even if Launchpad hasn't processed a build or binary packages yet, +git-ubuntu catches up on source package updates as soon as Launchpad publishes +them. + + +### Git-ubuntu and Launchpad + +Launchpad is the platform where Ubuntu development happens. But it is separate +from git-ubuntu: + +* Launchpad provides the machinery that validates, builds and publishes + packages. + +* Launchpad also provides the hosting for the git-ubuntu repositories, and the + mechanism for developers to collaborate on them through repository forks and + merge proposals with comment and voting facilities. + +* Git-ubuntu maintains the git-ubuntu repositories in Launchpad. The git-ubuntu + importer service clones them, scans and downloads Launchpad source + publications updates, converts these into repository updates and pushes the + updated repositories back to Launchpad. + +The importer itself is provided by the CLI as the `import` subcommand. It's +possible to run the tool locally if the importer service is unavailable or +inaccessible, and for development of the git-ubuntu importer itself. Similarly, +the components that schedule the imports are available as the +`importer-service-{broker,poller,worker}` subcommands. + + +## CLI + +The {command}`git-ubuntu` CLI is installed with `sudo snap install --classic git-ubuntu`. It adds `ubuntu` subcommands to the `git` command. For example: `git ubuntu clone hello`. + +Just like the `git` command itself, most git-ubuntu subcommands expect to be +running in the context of a git repository. + + +### When to use the CLI + +Since the git-ubuntu importer service hosts its imported repositories in +Launchpad, there is a regular public URL to clone from for each source package, +and you can do this using plain git. So it's not strictly necessary to use the +git-ubuntu CLI at all. + +However use of the git-ubuntu CLI gives you the following: + +* Convenience. For example: + + * `git ubuntu clone ` clones a git-ubuntu repository without you + having to look up the URL, and adds an additional remote that corresponds + to your personal space on Launchpad, so you can later easily push to it to + propose a merge. + + * `git ubuntu remote add ` adds a peer's personal repository space + for the same package, so you can easily fetch and review their merge + proposals without typing long URLs. + +* `git log` is automatically configured to display "changelog notes" if you + used `git ubuntu clone`, so it's easier to see summaries of what changed + in synthesized commits. + +* Workaround hooks are automatically added by `git ubuntu clone` to help + detect and deal with edge case issues, such as + {ref}`empty-directories`. + + +## Further reading + +* [git-ubuntu source](https://git.launchpad.net/git-ubuntu) +* [git-ubuntu bug tracker](https://bugs.launchpad.net/git-ubuntu/) diff --git a/docs/how-ubuntu-is-made/processes/index.md b/docs/how-ubuntu-is-made/processes/index.md index 3b361c0a..763c4ee0 100644 --- a/docs/how-ubuntu-is-made/processes/index.md +++ b/docs/how-ubuntu-is-made/processes/index.md @@ -47,7 +47,23 @@ sponsorship ``` -#### Proposed migration +### Git-ubuntu + +Explanation of the git-ubuntu importer service. See also {ref}`how-to-handle-git-ubuntu-uploads`. + +```{toctree} +:maxdepth: 1 + +git-ubuntu/index +``` + +* {ref}`git-ubuntu-design-goals-and-principles` +* {ref}`changes-file-headers` +* {ref}`empty-directories` + + + +### Proposed migration The process of moving (uploaded or merged) packages from the `-proposed` {term}`pocket` to the `-release` pocket to make them available to users: diff --git a/docs/redirects.txt b/docs/redirects.txt index cc2c4562..0b97cd50 100644 --- a/docs/redirects.txt +++ b/docs/redirects.txt @@ -114,7 +114,9 @@ who-makes-ubuntu/joining/dmb-index who-makes-ubuntu/developers/dmb-index/ who-makes-ubuntu/index-specialist-teams/ who-makes-ubuntu/specialist-teams/ contributors/advanced/merge-a-package/ contributors/merging/ -contributors/sync-process/ contributors/request-a-sync/ +contributors/sync-process/ contributors/uploading/request-a-sync/ +contributors/request-a-sync/ contributors/uploading/request-a-sync/ +contributors/find-a-sponsor/ contributors/uploading/find-a-sponsor/ contributors/bug-fix/build-packages/ contributors/bug-fix/build-packages-in-a-ppa/ contributors/bug-fix/download-new-upstream-version/ contributors/bug-fix/get-a-new-upstream-version/ contributors/bug-fix/package-building/ contributors/bug-fix/build-packages-in-a-ppa/ From c4448e869f9f989fce60c69125820505a6efc95a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Kr=C3=A1tk=C3=BD?= Date: Mon, 13 Oct 2025 17:34:14 +0200 Subject: [PATCH 4/6] Apply suggestions from code review Co-authored-by: Jonas Jelten --- .../advanced/handle-git-ubuntu-uploads.md | 103 ++++++++---------- .../advanced/upload-with-rich-history.md | 22 ++-- 2 files changed, 57 insertions(+), 68 deletions(-) diff --git a/docs/contributors/advanced/handle-git-ubuntu-uploads.md b/docs/contributors/advanced/handle-git-ubuntu-uploads.md index f2c7ce95..73de1ed3 100644 --- a/docs/contributors/advanced/handle-git-ubuntu-uploads.md +++ b/docs/contributors/advanced/handle-git-ubuntu-uploads.md @@ -22,25 +22,26 @@ These steps are described in the sections below. ## Checkout the source package's official git-ubuntu repo -```none -$ git ubuntu clone [dir-name] +```console +git ubuntu clone [dir-name] ``` For example, for a contribution to dovecot, you might run: ```none -$ git ubuntu clone dovecot dovecot-gu +```console +git ubuntu clone dovecot ``` -## Add remote tracking branches to a git-ubuntu checkout +## 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: -```none -$ git ubuntu remote add -$ git checkout "/" -b "" +```console +git ubuntu remote add $sponsoree $url +git switch -c lp$id-$desc-$release $sponsoree/$branch_name ``` @@ -52,8 +53,8 @@ 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: -```none -$ git branch -av | grep pkg/ubuntu/jammy +```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 @@ -65,8 +66,8 @@ 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: -```none -$ git checkout pkg/ubuntu/jammy-devel -b jammy-devel +```console +git switch -c jammy-devel pkg/ubuntu/jammy-devel ``` Be aware that the -devel branch will include any changes currently @@ -84,21 +85,21 @@ 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. -```none -$ mkdir review-lp -$ cd review-lp -$ wget -$ git ubuntu clone -gu -$ cd -gu -$ git checkout pkg/ubuntu/-devel -b review-lp- -$ debdiff-apply < ../ -$ git commit debian/changelog -m changelog -$ changes=$(dpkg-parsechangelog -S Changes | grep "^ ") -$ update-maintainer -r -Restoring original maintainer: ... -$ git commit -a -m "${changes}" -$ update-maintainer -$ git commit debian/control* -m "update-maintainer" +```console +git ubuntu clone $package && cd $package +git switch -c lp$bugnumber-$description-$release pkg/ubuntu/$release-devel + +debdiff-apply < ../$debdiff_file + +# create cleaned up commits (except changelog and maintainer) +git add -p ... +git commit + +git commit debian/changelog -m changelog + +# if there was no debian delta before: +update-maintainer +git commit debian/control* -m "update-maintainer" ``` That should result in a reasonable facsimile of a git ubuntu style @@ -106,8 +107,7 @@ 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, you can proceed with reviewing and building using the -techniques described elsewhere. +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). @@ -138,42 +138,31 @@ empty directories won't get copied forward. Example of use: -```none -$ git ubuntu clone apache2 -$ cd apache2 -$ git tag -f base +```console +git ubuntu clone apache2 && cd apache2 +git tag -f base -$ git-ubuntu.experimental-emptydirfixup fix-many base -$ dpkg-buildpackage $(git ubuntu prepare-upload args) -S +git-ubuntu.experimental-emptydirfixup fix-many base +debuild -S $(git ubuntu prepare-upload args) ``` ## Build a git-ubuntu source package branch for uploading -Assuming you have the branch checked out that you want to build, and are -running inside an Ubuntu release matching the MP's release (e.g. in an -LXC container), here is one way to build the source package from the -branch: +Check out the branch to build, maybe adjust `debian/changelog` to contain `~ppa1` as suffix, then build the source package: -```none -$ install-build-deps -$ git ubuntu export-orig [--for-merge] -$ upload_args=$(git ubuntu prepare-upload args) -$ debuild --no-lintian -S -uc -us ${upload_args} +```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. -The `install-build-deps` script can be found in the ubuntu-helpers repository, or -you can download it directly from [install-build-deps](https://git.launchpad.net/~ubuntu-server/+git/ubuntu-helpers/plain/bryce/install-build-deps). - -This calculates the build requirements using the debian/control file in -the current directory tree. This is more reliable than using -`apt-get build-dep ` when the changes you're reviewing have -some package dependency changes, such as when merging a new upstream -package. +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 @@ -181,12 +170,12 @@ package. Here's a workflow snippet to toss the changes into a PPA and run tests on that: -```none -$ ppa="ppa:/-review-lp" -$ ppa create ${ppa} -$ dput ${ppa} -$ ppa wait ${ppa} -$ ppa tests ${ppa} +```console +ppaid="ppa:/-review-lp" +ppa create $ppaid +dput $ppaid $package.changes +ppa wait $ppaid +ppa tests $ppaid ``` The last command will print clickable links to trigger the corresponding diff --git a/docs/contributors/advanced/upload-with-rich-history.md b/docs/contributors/advanced/upload-with-rich-history.md index 6408f8cf..c43e367d 100644 --- a/docs/contributors/advanced/upload-with-rich-history.md +++ b/docs/contributors/advanced/upload-with-rich-history.md @@ -26,9 +26,9 @@ These instructions make the following assumptions: Push your branch, create the source package and changes file and upload them as follows: -```none -$ dpkg-buildpackage $(git ubuntu prepare-upload args) -S -$ dput ubuntu ../__source.changes +```console +dpkg-buildpackage -S $your_options $(git ubuntu prepare-upload args) +dput ubuntu ../__source.changes ``` `git ubuntu prepare-upload args` will push your branch to your namespace @@ -58,18 +58,18 @@ Identify three items: Call `dpkg-buildpackage` as follows: -```none -$ dpkg-buildpackage -S \ - --changes-option=-DVcs-Git= \ - --changes-option=-DVcs-Git-Ref= \ - --changes-option=-DVcs-Git-Commit= \ - +```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: -```none -$ dput ubuntu ../__source.changes +```console +dput ubuntu ../__source.changes ``` From c47bf421a19d9639b5c3f49af02fb7123931fa68 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Kr=C3=A1tk=C3=BD?= Date: Mon, 13 Oct 2025 17:36:39 +0200 Subject: [PATCH 5/6] Apply suggestions from code review Co-authored-by: Jonas Jelten --- docs/contributors/advanced/upload-with-rich-history.md | 8 ++++---- .../git-ubuntu/git-ubuntu-design-goals-and-principles.rst | 2 +- docs/how-ubuntu-is-made/processes/git-ubuntu/index.md | 4 ++-- docs/how-ubuntu-is-made/processes/index.md | 2 +- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/contributors/advanced/upload-with-rich-history.md b/docs/contributors/advanced/upload-with-rich-history.md index c43e367d..9e2b1f80 100644 --- a/docs/contributors/advanced/upload-with-rich-history.md +++ b/docs/contributors/advanced/upload-with-rich-history.md @@ -86,10 +86,10 @@ These instructions make the following assumptions: Push your branch, adjust your changes file, re-sign it and upload as follows:: -```none -$ git ubuntu prepare-upload mangle ../__source.changes -$ debsign ../__source.changes -$ dput ubuntu ../__source.changes +```console +git ubuntu prepare-upload mangle ../__source.changes +debsign ../__source.changes +dput ubuntu ../__source.changes ``` `git ubuntu prepare-upload mangle` will push your branch to your diff --git a/docs/how-ubuntu-is-made/processes/git-ubuntu/git-ubuntu-design-goals-and-principles.rst b/docs/how-ubuntu-is-made/processes/git-ubuntu/git-ubuntu-design-goals-and-principles.rst index 90407177..eca9476f 100644 --- a/docs/how-ubuntu-is-made/processes/git-ubuntu/git-ubuntu-design-goals-and-principles.rst +++ b/docs/how-ubuntu-is-made/processes/git-ubuntu/git-ubuntu-design-goals-and-principles.rst @@ -1,6 +1,6 @@ .. _git-ubuntu-design-goals-and-principles: -Git-ubuntu design goals and principles +git-ubuntu design goals and principles ====================================== diff --git a/docs/how-ubuntu-is-made/processes/git-ubuntu/index.md b/docs/how-ubuntu-is-made/processes/git-ubuntu/index.md index 5591917c..97f75e43 100644 --- a/docs/how-ubuntu-is-made/processes/git-ubuntu/index.md +++ b/docs/how-ubuntu-is-made/processes/git-ubuntu/index.md @@ -1,5 +1,5 @@ (git-ubuntu)= -# Git-ubuntu +# git-ubuntu ```{toctree} :maxdepth: 1 @@ -46,7 +46,7 @@ git-ubuntu catches up on source package updates as soon as Launchpad publishes them. -### Git-ubuntu and Launchpad +### git-ubuntu and Launchpad Launchpad is the platform where Ubuntu development happens. But it is separate from git-ubuntu: diff --git a/docs/how-ubuntu-is-made/processes/index.md b/docs/how-ubuntu-is-made/processes/index.md index 763c4ee0..361ba40a 100644 --- a/docs/how-ubuntu-is-made/processes/index.md +++ b/docs/how-ubuntu-is-made/processes/index.md @@ -47,7 +47,7 @@ sponsorship ``` -### Git-ubuntu +### git-ubuntu Explanation of the git-ubuntu importer service. See also {ref}`how-to-handle-git-ubuntu-uploads`. From 2d5060f34468d1cfab6ffc3413f4ff6dcad2b392 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Kr=C3=A1tk=C3=BD?= Date: Mon, 13 Oct 2025 18:14:36 +0200 Subject: [PATCH 6/6] Apply feedback by @TheJJ --- docs/conf.py | 1 + .../advanced/handle-git-ubuntu-uploads.md | 33 ++-- .../setup/set-up-for-ubuntu-development.md | 27 ++-- ...git-ubuntu-design-goals-and-principles.rst | 143 ------------------ .../processes/git-ubuntu/index.md | 96 ++++++++---- docs/how-ubuntu-is-made/processes/index.md | 1 - 6 files changed, 98 insertions(+), 203 deletions(-) delete mode 100644 docs/how-ubuntu-is-made/processes/git-ubuntu/git-ubuntu-design-goals-and-principles.rst diff --git a/docs/conf.py b/docs/conf.py index b06f1622..fb1f5281 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -402,6 +402,7 @@ None, ), "sru": ("https://canonical-sru-docs.readthedocs-hosted.com/en/latest/", None), + "launchpad": ("https://documentation.ubuntu.com/launchpad/", None), } diff --git a/docs/contributors/advanced/handle-git-ubuntu-uploads.md b/docs/contributors/advanced/handle-git-ubuntu-uploads.md index 73de1ed3..0be9e701 100644 --- a/docs/contributors/advanced/handle-git-ubuntu-uploads.md +++ b/docs/contributors/advanced/handle-git-ubuntu-uploads.md @@ -28,7 +28,6 @@ git ubuntu clone [dir-name] For example, for a contribution to dovecot, you might run: -```none ```console git ubuntu clone dovecot ``` @@ -85,22 +84,30 @@ 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. -```console -git ubuntu clone $package && cd $package -git switch -c lp$bugnumber-$description-$release pkg/ubuntu/$release-devel +1. Clone the package and apply the debdiff: -debdiff-apply < ../$debdiff_file + ```console + git ubuntu clone $package && cd $package + git switch -c lp$bugnumber-$description-$release pkg/ubuntu/$release-devel -# create cleaned up commits (except changelog and maintainer) -git add -p ... -git commit + debdiff-apply < ../$debdiff_file + ``` -git commit debian/changelog -m changelog +1. Create cleaned up commits (except changelog and maintainer): -# if there was no debian delta before: -update-maintainer -git commit debian/control* -m "update-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 diff --git a/docs/contributors/setup/set-up-for-ubuntu-development.md b/docs/contributors/setup/set-up-for-ubuntu-development.md index 79c11a9e..fb5a4f93 100644 --- a/docs/contributors/setup/set-up-for-ubuntu-development.md +++ b/docs/contributors/setup/set-up-for-ubuntu-development.md @@ -99,20 +99,6 @@ so, create a new 4096-bit one and deprecate the old one in Launchpad, GitHub, etc. -(keyring-with-plaintext-storage)= -### Keyring with plaintext storage - -See {ref}`keyring-integration` for details on how `git-ubuntu` uses keyring. If -you want to reconfigure keyring to use plaintext storage to avoid getting -keyring password prompts, create the file -`~/.local/share/python_keyring/keyringrc.cfg` with the following contents: - -```none -[backend] -default-keyring=keyrings.alt.file.PlaintextKeyring -``` - - (git)= ### Git @@ -436,3 +422,16 @@ If you're operating from a GUI, this can be useful: $ eval `dbus-launch --sh-syntax` ``` + +(keyring-with-plaintext-storage)= +### Keyring with plaintext storage + +See `git-ubuntu` {ref}`keyring-integration` for details on how `git-ubuntu` uses keyring. If +you want to reconfigure keyring to use plaintext storage to avoid getting +keyring password prompts, create the file +`~/.local/share/python_keyring/keyringrc.cfg` with the following contents: + +```none +[backend] +default-keyring=keyrings.alt.file.PlaintextKeyring +``` diff --git a/docs/how-ubuntu-is-made/processes/git-ubuntu/git-ubuntu-design-goals-and-principles.rst b/docs/how-ubuntu-is-made/processes/git-ubuntu/git-ubuntu-design-goals-and-principles.rst deleted file mode 100644 index eca9476f..00000000 --- a/docs/how-ubuntu-is-made/processes/git-ubuntu/git-ubuntu-design-goals-and-principles.rst +++ /dev/null @@ -1,143 +0,0 @@ -.. _git-ubuntu-design-goals-and-principles: - -git-ubuntu design goals and principles -====================================== - - -Consistency and tool unification --------------------------------- - -One measure of success for git-ubuntu is to reduce or eliminate the occasions -where an experienced Ubuntu developer has to say "that package is special" when -a new developer or drive-by contributor is asking for help on performing a -routine task. - -Another measure is the amount of setup required before a developer can perform -a task, such as test building a package from a source tree in a reproducible -way. - -For example, in answer to the following questions, git-ubuntu already -eliminates the "this package is special" excuse for packages covered by -git-ubuntu repositories: - -* "Where can I clone the git tree for package X"? Without git-ubuntu, "this - package is special" is needed when a Vcs-Git header doesn't exist, or does - exist but no git branch is maintained for the Ubuntu delta, or does exist but - the header hasn't been updated to point to it. - -The following are medium term goals: - -* "How do I build package X"? Right now, the recommended :command:`sbuild` method - involves setting up :term:`chroots `, arranging :command:`sbuild` group membership, and :command:`sbuild` - default configuration expects an MTA that also requires setting up. - -* "How do I patch the version of package X that Ubuntu ships in release Y"? - Right now, this usually involves knowledge of quilt and the "3.0 (quilt)" - Debian source package format. - -Because git-ubuntu uses a single scheme to represent package source trees in -git, and also a single schema for all branch and tag names, automation that -operates on package sources is easier to write, including automation that needs -visibility across multiple package versions at once. For example, it's easier -to write automation to help validate SRUs since such automation can easily -inspect the current state of different releases and pockets. Instead of using -the Launchpad API for this kind of inspection, the tooling can inspect this -state using the same mechanism it can use to inspect the existing published -source tree and the source trees in Launchpad's queues. git is the single tool -that can be used for all of this. - -Single source of truth ----------------------- - -Uploads arrive into Ubuntu regardless of git-ubuntu, such as via syncs from -Debian or just direct uploads using ``dput`` without git-ubuntu. Launchpad is -the authority that publishes Ubuntu packages via apt. So Launchpad, not -git-ubuntu, is the authority and "single source of truth" of what the source -tree is for a particular package, and what they were historically. - -git-ubuntu is designed to be able to guarantee that its git repositories do -actually represent this single source of truth. Therefore, its git repositories -are necessarily derived from and form a view onto Launchpad's single source of -truth, and cannot define it. - -Integrity requirements ----------------------- - -Since git-ubuntu's git repositories are merely a view of Launchpad's single -source of truth, its refs (branches, tags, etc) must also be derived from that -truth and therefore must be read-only from the git perspective. Otherwise, -developers would be able to push a different truth to the git repositories that -do not reflect the truth in Launchpad, and that would defeat the purpose of -git-ubuntu in the first place. - -Similarly, the commits that correspond to specific published source package -versions must match what was uploaded exactly, so that developers can trust -that what they see in the git repository corresponds to what was actually -published. - -How uploads map to commits --------------------------- - -In the common case, git-ubuntu achieves this by synthesizing a commit from what -was uploaded to Launchpad as a package upload. In this case, all the changes -from the previous upload are "squashed" into a single commit. - -However, the integrity requirement is just that the specific commits that -correspond to package uploads match. Intermediate commits are permitted, and -these need not be restricted for integrity purposes. - -Therefore, this schema allows for developers to provide a "richer" path that -describes how they arrived at their upload in more granular detail, in the -git usual way by providing intermediate commits. In git-ubuntu, since we aren't -the single source of truth, we must handle this specially to maintain our other -integrity requirements, and call this concept "rich history". - - -.. _rich-history: - -Rich history ------------- - -git-ubuntu's rich history mechanism has some requirements: - -#. The developer must provide rich history commits at the time of the dput-based (non-git) upload. - -#. These commits must remain available to the git-ubuntu importer until after it has imported them. - -#. The tree of the final rich history commit provided must precisely match the tree of the upload. There exist some edge cases necessary to maintain a lossless mapping from source package to git tree where git-ubuntu defines exactly what should happen to the tree; the rich history commit must do precisely the same to meet this requirement. - -#. The specification defines some further requirements; the general idea is that the rich history commits must be based on a commit that corresponds to a previous import and your upload must preserve the old ``debian/changelog`` entries in the usual way. - -If these requirements are met, then git-ubuntu will use your commits for its -import instead of synthesizing one. - -See :ref:`how-to-upload-with-rich-history` for instructions on providing rich history to the -importer. - - -Determining the parent ----------------------- - -Trust the uploader to base it correctly by looking at :file:`debian/changelog`. -This leads to "force pushes". - - -.. _keyring-integration: - -Keyring integration -------------------- - -Some git-ubuntu subcommands (e.g. ``git-ubuntu submit``) require authenticated -access to the Launchpad API. The first time you do this, you will be prompted -to authenticate in a web browser. If successful, the authenticated API key will -then be saved in your local keyring. You may be prompted for a password. This -password is used to encrypt your local keyring. If you don't yet have a local -keyring, the password you provide will be used to encrypt it. If you already -have a local keyring, the password you provide is the one required to decrypt -it. - -See :ref:`keyring-with-plaintext-storage` for instructions on configuring keyring to use -plaintext password storage instead, to avoid getting keyring password prompts. - -git-ubuntu uses `launchpadlib `_ for Launchpad API access. This -library in turn uses the `Python keyring package `_ for credential storage. If you see a password prompt, it is because the keyring package's defaults in your particular environment require encrypted password-based credential storage. Configure this to your needs by following the `keyring documentation `_. diff --git a/docs/how-ubuntu-is-made/processes/git-ubuntu/index.md b/docs/how-ubuntu-is-made/processes/git-ubuntu/index.md index 97f75e43..992db19a 100644 --- a/docs/how-ubuntu-is-made/processes/git-ubuntu/index.md +++ b/docs/how-ubuntu-is-made/processes/git-ubuntu/index.md @@ -5,7 +5,6 @@ :maxdepth: 1 :hidden: -Design goals and principles changes-file-headers empty-directories ``` @@ -19,11 +18,47 @@ easier "drive-by" contributions. git-ubuntu comprises two components: +1. The {command}`git-ubuntu` CLI tool contains all its provided automation for developer use. + 1. The git-ubuntu importer service runs the importer to maintain git repositories of Ubuntu packages in Launchpad. -1. The {command}`git-ubuntu` CLI tool contains all its provided automation for developer -use. + +## CLI + +The {command}`git-ubuntu` CLI is installed with `sudo snap install --classic git-ubuntu`. It adds `ubuntu` subcommands to the `git` command. For example: `git ubuntu clone hello`. + +Just like the `git` command itself, most git-ubuntu subcommands expect to be +running in the context of a git repository. + + +### When to use the CLI + +Since the git-ubuntu importer service hosts its imported repositories in +Launchpad, there is a regular public URL to clone from for each source package, +and you can do this using plain git. So it's not strictly necessary to use the +git-ubuntu CLI at all. + +However use of the git-ubuntu CLI gives you the following: + +* Convenience. For example: + + * `git ubuntu clone ` clones a git-ubuntu repository without you + having to look up the URL, and adds an additional remote that corresponds + to your personal space on Launchpad, so you can later easily push to it to + propose a merge. + + * `git ubuntu remote add ` adds a peer's personal repository space + for the same package, so you can easily fetch and review their merge + proposals without typing long URLs. + +* `git log` is automatically configured to display "changelog notes" if you + used `git ubuntu clone`, so it's easier to see summaries of what changed + in synthesized commits. + +* Workaround hooks are automatically added by `git ubuntu clone` to help + detect and deal with edge case issues, such as + {ref}`empty-directories`. ## Importer service @@ -58,11 +93,6 @@ from git-ubuntu: mechanism for developers to collaborate on them through repository forks and merge proposals with comment and voting facilities. -* Git-ubuntu maintains the git-ubuntu repositories in Launchpad. The git-ubuntu - importer service clones them, scans and downloads Launchpad source - publications updates, converts these into repository updates and pushes the - updated repositories back to Launchpad. - The importer itself is provided by the CLI as the `import` subcommand. It's possible to run the tool locally if the importer service is unavailable or inaccessible, and for development of the git-ubuntu importer itself. Similarly, @@ -70,41 +100,43 @@ the components that schedule the imports are available as the `importer-service-{broker,poller,worker}` subcommands. -## CLI +(rich-history)= +## Rich history -The {command}`git-ubuntu` CLI is installed with `sudo snap install --classic git-ubuntu`. It adds `ubuntu` subcommands to the `git` command. For example: `git ubuntu clone hello`. +git-ubuntu's rich history mechanism has some requirements: -Just like the `git` command itself, most git-ubuntu subcommands expect to be -running in the context of a git repository. +1. The developer must provide rich history commits at the time of the dput-based (non-git) upload. +1. These commits must remain available to the git-ubuntu importer until after it has imported them. -### When to use the CLI +1. The tree of the final rich history commit provided must precisely match the tree of the upload. There exist some edge cases necessary to maintain a lossless mapping from source package to git tree where git-ubuntu defines exactly what should happen to the tree; the rich history commit must do precisely the same to meet this requirement. -Since the git-ubuntu importer service hosts its imported repositories in -Launchpad, there is a regular public URL to clone from for each source package, -and you can do this using plain git. So it's not strictly necessary to use the -git-ubuntu CLI at all. +1. The specification defines some further requirements; the general idea is that the rich history commits must be based on a commit that corresponds to a previous import and your upload must preserve the old `debian/changelog` entries in the usual way. -However use of the git-ubuntu CLI gives you the following: +If these requirements are met, then git-ubuntu will use your commits for its +import instead of synthesizing one. -* Convenience. For example: +See {ref}`how-to-upload-with-rich-history` for instructions on providing rich history to the +importer. - * `git ubuntu clone ` clones a git-ubuntu repository without you - having to look up the URL, and adds an additional remote that corresponds - to your personal space on Launchpad, so you can later easily push to it to - propose a merge. - * `git ubuntu remote add ` adds a peer's personal repository space - for the same package, so you can easily fetch and review their merge - proposals without typing long URLs. +(keyring-integration)= +## Keyring integration -* `git log` is automatically configured to display "changelog notes" if you - used `git ubuntu clone`, so it's easier to see summaries of what changed - in synthesized commits. +Some {command}`git-ubuntu` subcommands (e.g. `git-ubuntu submit`) require authenticated +access to the Launchpad API. The first time you do this, you will be prompted +to authenticate in a web browser. If successful, the authenticated API key will +then be saved in your local keyring. You may be prompted for a password. This +password is used to encrypt your local keyring. If you don't yet have a local +keyring, the password you provide will be used to encrypt it. If you already +have a local keyring, the password you provide is the one required to decrypt +it. -* Workaround hooks are automatically added by `git ubuntu clone` to help - detect and deal with edge case issues, such as - {ref}`empty-directories`. +See {ref}`keyring-with-plaintext-storage` for instructions on configuring keyring to use +plaintext password storage instead, to avoid getting keyring password prompts. + +git-ubuntu uses {external:std:ref}`launchpadlib ` for Launchpad API access. This +library in turn uses the [Python keyring package](https://pypi.org/project/keyring/) for credential storage. If you see a password prompt, it is because the keyring package's defaults in your particular environment require encrypted password-based credential storage. Configure this to your needs by following the [keyring documentation](https://pypi.org/project/keyring/). ## Further reading diff --git a/docs/how-ubuntu-is-made/processes/index.md b/docs/how-ubuntu-is-made/processes/index.md index 361ba40a..cbb541f5 100644 --- a/docs/how-ubuntu-is-made/processes/index.md +++ b/docs/how-ubuntu-is-made/processes/index.md @@ -57,7 +57,6 @@ Explanation of the git-ubuntu importer service. See also {ref}`how-to-handle-git git-ubuntu/index ``` -* {ref}`git-ubuntu-design-goals-and-principles` * {ref}`changes-file-headers` * {ref}`empty-directories`