Issue 316: fixing bugs

[vpa1977]

Description

This PR performs refactoring of the fixing-bugs section:

• introduce a new building section
• introduce a new updating section
• Updating/Submit a Merge proposal -> a lot of duplicates with g-u merge proposal in merge process. Merged those pages as an example how fix-bug-in-a-package will look like.
• Bug fixing section:
  • split fix-bug-in-a-package
  • referenced building and updating sections
  • renamed proposing-a-change to bugfixng-workflow

---

Related issue

#316

Checklist

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

---

Additional notes (optional)

Add any extra information or context that reviewers may need to know. This could include testing instructions, screenshots, or links to related discussions.

---

Thank you for contributing to the Ubuntu Project documentation!

[vpa1977]

@dviererbe @rkratky would it be possible to take a look and tell if I am going in the right direction with it?

[rkratky]

Thank you, @vpa1977. I'll do a proper review later today, but just want to note that this PR will run into conflicts with the work being done in #431. That's expected, and fixing the conflict shouldn't pose a big problem once either one of these PRs is merged -- just want to give you both a heads up (cc @BAMF0).

[rkratky]

@vpa1977, finally was able to review the whole thing. Really nice. I like the reorg.

One question though: I see you created the new building/ directory directly under docs/, i.e. outside of the contributors/ directory -- yet the updating/ directory stayed there. Is there a reason for that?

(I'm generally not super-thrilled by the long URLs our dir structure creates, but as long as we have it, I suppose we should be consistent about it.)

[vpa1977]

@vpa1977, finally was able to review the whole thing. Really nice. I like the reorg.

One question though: I see you created the new building/ directory directly under docs/, i.e. outside of the contributors/ directory -- yet the updating/ directory stayed there. Is there a reason for that?

Oh, that's my mistake I will move it back under contributors.

[cpaelzer]

Hi @vpa1977

First of all it is lovely to see that all of us identified these sections as place for confusion. This is all good, as long as we make each step one in the right direction that is just what we need and eventually will be much less confusing \o/.

Many mentors and myself included things and had our mentees stumble over this section - so it is time to fix it. For example also @jugmac00 changing things and tracking to look at #546. There also was #431 by @BAMF0 changing some of the same. Since I send my folks to improve this after explaining they need to know - so I'm tagging them here for their awareness to not conflict with this effort.

---

I like that the top level entry now is more like a bit of an intro and that the major steps are outlined in the workflow. I like the grouping of the two builds, I'd still move it out of "fixing" as it is also needed for e.g. "new packages" or "updates/merges". But fixing #546 you can make part of this PR or leave it open for the next. If not we certainly we want to land this before moving further.

Recommendations/Asks

• in workflow -> "Identify the source package" you use apt-file, but that has to be set up explicitly. I guess we can assume that most of the time they have the failing thing on disk. Should we make the default path easier by using "dpkg -S <filename". apt-file is good but should become a "note: if you do not have it installed you might ...
• Since you grouped autopkgtest and install under "Build a fixed package" that header should IMHO be "Build and test a fixed package"
• in "once-the-fix-is-accepted" you hint at proposed migration and SRU (good), but do not link to their respective sections. So people now knowing are left with new terms they do not know, please make each of those paragraphs then point to the detailed sections so a ready can find more.
• this is even more intense in "Update the bug report" which should not have redundant statements about SRU handling and instead just be a paragraph on maybe "Update the bug report" and point to all the SRU details to the respective pages (let us not fix duplication in building by creating new duplication about the SRU things). If there has been anything on this page which is truly missing in the SRU section add it there as part of the PR.
• I like your approach but you are not going far enough yet. For example "bugfixing-workflow" has soooo much about checking "Check if the bug has been fixed" - this is like 2-3 pages. But then there is the extra page "check-if-is-it-already-fixed". Would it not make more sense to make "bugfixing-workflow" even more brief for ease of consumption and move much of it into the detail pages. That avoids the info to be in two places and at the same time makes the first read of the workflow easier to parse.

Suggestions

• I also like that there now is one "submit a merge proposal" but the nav bar highlighting goes mad. It highlights "fixing bugs" and "updating" at the same time. Should "submit a merge proposal" just move up to be a sibling and not a child of those?
• You seem to have done the same move for "Building" - also a mad nav bar. I find the same content at multiple places a level higher and under "fixing bugs". If this style is the way to go then "submit a merge" could be a sibling to building"
• Same for "package tests" which is under "fixing bugs" AND under "fixing bugs -> build a fixed package"
• On those cases you might want the authors input - I'm not sure what the best way to "refer from each place". I can see the argument to have it show up in many places so you do not feel you "leave what you are reading". But at the same time I'm confused by finding the same in many different places and the nav bar going nuts. Maybe your approach is the right one - I'm not sure @s-makin @rkratky ?