[gentoo-dev] Re: Prefix bootstrap script maintainability (Was: No more stable keywords for Games)

[R0b0t1]

Hello friends!

On Sun, Nov 19, 2017 at 6:54 PM, Benda Xu <heroxbd@g.o> wrote:
> Greetings R0b0t1,
>
> R0b0t1 <r030t1@×××××.com> writes:
>
>> It is one thing to say that contributions to the main Portage tree
>> require some standards to be upheld, but these standards do not seem
>> to be applied consistently. For example, crossdev, genkernel, and the
>> bootstrap-prefix and bootstrap-rap scripts are more or less
>> unmaintainable disasters.
>> [...]
>> and the bootstrap scripts are poorly explained with no extant
>> documentation and a workflow that does not clearly fit into Gentoo (or
>> more properly Portage) development at large.
>
> As one of the maintainers of the bootstrap-prefix (and bootstrap-rap), I
> acknowledge that the script is a result of accumulated contributions
> from multiple people, with rounds of refactorizations in the past
> several years. But it is well understood and maintainable.
>
> I would like to remind you that, the script is a reflection of the
> instrinsic complexity to compile a workable Gentoo from zero, in a wild
> variety of environments from handhold embedded devices to top 10
> supercomputers, from GNU/Linux, MacOS to Solaris/OpenIndiana and Cygwin.
>

That is fine, but I am more talking about the burden of trying to
understand what is going on. Nowhere is there a simple list of steps
that the bootstrap scripts take. The code is sparsely commented and
intent is not readily inferred from context. Some of this is related
to the packages in question, and I can not expect the scripts to e.g.
summarize the autotools options passed to the respective software, but
justification for why what is taking place is taking place should have
been a priority.

The typical response of "read the code" (which I have read more than a
few places) indicates to me that someone does not value my time and
has not bothered to remember what they have done, or why. Besides the
insult to future contributors this train of thought reflects poorly on
the quality of the author's work and the esteem with which they hold
the fruits of their labor.

I feel this manifests as the original developers being unlikely to
contribute because they have lost track of the various interacting
components and would need to invest a substantial amount of time in
re-understanding their own work. There are other projects where I have
observed the main authors undertake what appear to be, at first
glance, very technical changes due to an offhand comment by a mailing
list user.

These projects all seem to have been well documented.

> Don't be pissed off if it couldn't be hacked in several hours to be
> ported to ppc64.  That's life: anything worth doing will not be easy.
>

Understanding an existing codebase should not be a technical
challenge. I had to resort to reimplementing all of the steps myself,
in part to understand if they were done properly in the first place.

In the case of the bootstrap scripts, minor problems are very hard to
diagnose because of limited feedback given, and the difficulty of
integrating what feedback is available into the overall setup process.

> For the standards and documentation, yes, the recommended workflow had
> better be carved into stone.  That's where things should be improved.
>

Unfortunately these are things that the original authors should
produce. Experience has shown me that documentation written by
ancillary contributors that do not have deep experience with the code
base is poor.

Respectfully,
     R0b0t1