RE: review of documentation about creating new ports?
Please remove me from your listserve-----Original Message-----
From: Paul Wise <pabs@debian.org>
Sent: Friday, June 30, 2023 10:32 PM
To: debian-l10n-english@lists.debian.org
Subject: Re: review of documentation about creating new ports?
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
Reply to: