Re: review of documentation about creating new ports?
Paul Wise <pabs@debian.org> writes:
> https://wiki.debian.org/PortsDocs/New
>
> At this point I believe the document is fairly complete and correct,
> so it would be great to have it reviewed for spelling, grammar and
> consistency of jargon and style.
> The audience is companies that have a Debian port to their own ISA
> internally and want to make it official, as well as companies or
> enthusiasts creating entirely new Debian ports for other operating
> system kernels or niche/new ISAs.
You might want to include this para on audience at the top. (although,
under "Preparation" it says a "financial sponsor" is needed which seems
unlikely for "enthusiasts")
> The people reading it are likely to
> be from around the world, some may not have good English but are
> likely
> already fairly technical, probably having done porting work before.
> They may be new to Debian and unfamiliar with our culture and jargon.
I had a quick read - obviously best to ask people who have done this
work if it gives them the right info, but it looked at about the right
level of jargon etc to my non-expert eyes.
Maybe i am too far from the target audience but i thought:
- 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.
The later sections seem better in this regard, perhaps as they are more
detailed: this seems backwards: you want to give more help for people in
the early stages, and by the time you get to "unofficial port" status the
process should be more understood.
- 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
- 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!
Detailed points:
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)
- in first step "detail the reasons" could be clearer as to where?
(debian wiki? email list? company website?)
- there are several "register account" type steps but
nothing saying why/what the account is to be used for.
- 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?)
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?)
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)
- perhaps the reference to build-essential needs a link/explanation
(and is this the same as 'build-essential packages' in the next bullet)
- i was surprised that there was nothing about d-i by now (it is mentioned much later)
- 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
Reply to: