Thanks for all the feedback, here are the resulting changes: https://wiki.debian.org/PortsDocs/New?action=diff&rev2=99&rev1=82 On Fri, 2023-06-30 at 21:53 +0100, RL wrote: > You might want to include this para on audience at the top. I think the audience is reasonably clear from the first paragraph (and is self-selecting based on that), the one in my email was more for context for this mailing list. > (although, under "Preparation" it says a "financial sponsor" is > needed which seems unlikely for "enthusiasts") At the top it says it documents the best way to do things but reality may differ. Creating a new port and maintaining it is a lot of work that is best done on a paid full-time basis. Of course some ports manage to get things done without that, but it isn't ideal. That said, I have softened that part a bit. > - the "why" could be clearer throughout the early sections page: it > reads like "complete this checklist and it will all be fine", and i > wonder if that is realistic, given debian's love of debate. In general, the document is very much a checklist to complete, I wanted it to be as simple as possible for folks who aren't yet part of Debian. The original checklist was the port template, but that wasn't giving folks enough context and explanation, so I fleshed it out into a doc. So far the loong64 folks have been progressing through it and I have been adding items as I notice they get stuck or when I notice that Debian folks ask questions or add requirements. I've added a few more justifications to various places. > - i was surprised there was not more in terms of how mature a port would > need to be before acceptance - it reads like all you have to do is > register some online accounts and write some patches but doesnt give > much of an idea about how debian will judge quality or whether > acceptance is guaranteed (although some of this is in the "official > port", some idea at the start might be helpful). Eg: are there > expectations about completeness/kernel support/number of units > sold/number of active developers/years of support/etc In general there are no hard requirements for the unofficial port stage, basically as long as you completed the bootstrap and can probably complete the first few steps that culminate in creating a buildd, then any unofficial port is likely to be accepted. We even have ports accepted that don't yet have build-essential (arc). > - I think it could explain the benefits of doing the journey are - > presumably once you get to "bootstrap", interested experts can use > debian on the port with difficulty, and by "official port", the hardware > is made accessible to end users (who might then report bugs and hardware > issues?). i.e., try and sell debian a bit as well! I've added intro paragraphs with the purpose/outcomes of each section. > Under Downstreaming: > - You mention XCC under Downstreaming, and in several places, but it is > not defined until "Unofficial port". (and it is spelled out but not > quite called 'XCC' in the intro) Moved the definition to the intro instead. > - in first step "detail the reasons" could be clearer as to where? > (debian wiki? email list? company website?) Just internally to the team, I've changed that to "write down" and added communicating the reasons to the discussion step. > - there are several "register account" type steps but > nothing saying why/what the account is to be used for. Added several sentences about that. > - the part about "please send an email to d-devel" might benefit from > extra detail - it says 'discussion', but is it > clear what this means - what are they meant to be discussing, and > what is the intended outcome: are they expecting some kind of yes/no > approval or is this just for information? (what information would > debian like them to provide?) Added a sentence fragment and sentence about that. > Under preparation > - is "working on the fork" enough - to me it suggests > generic work for some company: do you actually want "working on getting > the port into debian"? (and is it obvious what skills they need?) Rewrote that part to include that. > Under bootstrap > - "Prepare patches" is used in a couple of places: it this different to > the language used under "upstreaming" where it says 'get the necessary changes > included in' (which i thought was clearer) For patches there are two steps, first you write the patches/changes, then you get them included. In the upstreaming section those steps are all stuffed into the one item, but in the bootstrap stage you have to validate all your patches are working in Debian by running rebootstrap, fixing packages, repeating rebootstrap etc, once you have that completed, then you can get the changes included into various upstream projects and into rebootstrap. You don't really want to start upstreaming too early or you might need to get things reverted. > - perhaps the reference to build-essential needs a link/explanation > (and is this the same as 'build-essential packages' in the next bullet) Defined that better. > - i was surprised that there was nothing about d-i by now (it is > mentioned much later) d-i and debootstrap only use pre-built packages, the bootstrapping step uses rebootstrap to cross-build build-essential packages before they exist for the port, then more packages (esp. d-i udebs) can be built and then d-i image fragments can be built and the Debian installer ISOs built from the d-i udeb packages and d-i image fragments. > - i was surprised not to see something suggesting to get some interested people into the > DD/DM process and/or recruiting existing DDs/DMs to work on the port A lot of the steps can be done without any special status in Debian. Probably even the official port stage can be done by non-DDs if they are able to convince sponsors to do the build cycle breakage stuff. I've added items on getting more people involved, ensuring there is at least one DD in the team before the official port, hiring etc. -- bye, pabs https://wiki.debian.org/PaulWise
Attachment:
signature.asc
Description: This is a digitally signed message part