Hello friends! On Sun, Nov 19, 2017 at 6:54 PM, Benda Xu <hero...@gentoo.org> wrote: > Greetings R0b0t1, > > R0b0t1 <r03...@gmail.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