On Tue, 2023-09-05 at 21:58 +0200, Alexander Kanavin wrote: > On Tue, 5 Sept 2023 at 21:32, Richard Purdie > <[email protected]> wrote: > > This has proven contentious. Whilst I think it would help our docs > > maintenance, there are differing views: > > > > * it should be a directory for conflict reasons > > * we don't want a top level directory for this > > * we don't want a directory called "WIP" as it looks bad > > * we shouldn't have "partial" half way staging, either the docs are in > > repo or they're not > > > > I'm weary, I can't reconcile the views being expressed, some people > > haven't clearly haven't read or understood the proposal reasoning and > > its turning into a perfect bike shedding exercise. > > > > Much as I think it would be the right direction, some people won't be > > happy, the complaints are going to annoy me and I'm going to abandon > > the patch. > > Ugh, this is *not* the outcome I was expecting. Whoever is bike > shedding: shame on you. > > My two eurocents: > 1. Top level directory is fine. > 2. Top level directory called 'WIP' is fine, if it's not in a release > or a stable branch.
Well, some of the views are mine, some of them are not, I just tried to summarise for the archives. I am definitely against a WIP directory, the optics on that look terrible as it is too open to misinterpretation. There is no guarantee it would not make a release. Whilst I understand the technical merit of a directory, I really don't want a directory at all, the idea was to keep it really simple and it was working on the assumption that things would not be long in the file so merge conflicts would be minimal. With a clever choice of section separator, I think diff could be fooled into doing a decent job since we don't care about ordering. The bike shedding was going to quickly go in the direction of "we could have multiple directories, one for release note annotations, one for migration guide and one for docs changes, we could then have a script which did X and Y and magic and ... like python or ZZZ does" and this is partly why I'm just giving up, lots of excitement about complicated things which nobody has time to implement/maintain. Case in point, how many people have helped improve the docs build automation since it was created? The code mostly works but is horrible, it could be so much nicer. Given the direction things were looking to go, I don't have the time/energy to discuss/argue this any further. To be honest I'm struggling with things in general. Problematic patches come in and I end up arguing about them on my own even if I know that were they to merge I'd get a load of "why did you let X in when it causes Y performance to degrade or complicates Z". There is far to much reliance that I'll block things and therefore nobody else has to make the effort :/. > 3. I'm regularly adding features or changing behavior that require doc > updates. I'm just as regularly forgetting to document what I'm doing, > and this would've helped. The most notorious example is per image > license checks which went undocumented for several years. You're not alone, 2/2 was an example of my own making I was trying to head off issues with. Cheers, Richard
-=-=-=-=-=-=-=-=-=-=-=- Links: You receive all messages sent to this group. View/Reply Online (#187256): https://lists.openembedded.org/g/openembedded-core/message/187256 Mute This Topic: https://lists.openembedded.org/mt/101109943/21656 Group Owner: [email protected] Unsubscribe: https://lists.openembedded.org/g/openembedded-core/unsub [[email protected]] -=-=-=-=-=-=-=-=-=-=-=-
