5.10 Merge window, part 1
5.10 Merge window, part 1
Posted Oct 17, 2020 8:16 UTC (Sat) by darwi (subscriber, #131202)Parent article: 5.10 Merge window, part 1
Unfortunately, this is a sign of the maintainer not properly doing his or her job. Proper documentation should be a prerequisite of merging such patches.
Posted Oct 17, 2020 11:37 UTC (Sat)
by khim (subscriber, #9252)
[Link] (8 responses)
No. That would be horrible waste of resources. APIs are changed so radically during review process that writing adequate documentation for them (with examples and diagrams) is usually pointless. It could be redone 2, 3, even 10 times in extreme cases. But of course after new API is merged it's too late to write a documentation because, well, it's merged, why bother? Not sure how could that issue be adequately resolved…
Posted Oct 17, 2020 13:47 UTC (Sat)
by magfr (subscriber, #16052)
[Link]
There is actually another benefit of this - forcing documentation is kind of an "explain it to the duck" session for developers that forces them to think about their new shiny interface from another angle.
Posted Oct 17, 2020 14:34 UTC (Sat)
by dxin (guest, #136611)
[Link] (1 responses)
Posted Oct 18, 2020 21:39 UTC (Sun)
by roc (subscriber, #30627)
[Link]
Writing good documentation is also a clarifying process for everyone to understand exactly what the feature does and how it can and cannot be used. It's too easy to write some code and only later realize that the API is actually very difficult to use correctly; writing the documentation usually exposes this.
Posted Oct 17, 2020 17:11 UTC (Sat)
by mkubecek (guest, #130791)
[Link]
Posted Oct 19, 2020 20:33 UTC (Mon)
by darwi (subscriber, #131202)
[Link] (3 responses)
That’s a BS argument, sorry.
If the newly added user space API is really **that** contentious, then by the time the maintainer is going to merge the changes, he asks for a final iteration with proper documentation. Simply because if it’s not done at that moment, it might never be done in the future.
Stop justifying bad behavior please.
Posted Oct 19, 2020 23:38 UTC (Mon)
by Wol (subscriber, #4433)
[Link] (1 responses)
They say that no battle plan survives five minutes contact with the enemy, but without a plan you don't stand a chance.
Cheers,
Posted Oct 20, 2020 8:32 UTC (Tue)
by farnz (subscriber, #17727)
[Link]
This is where kerneldoc is great - documentation for the API sits with the implementation, and if you're working on the implementation, the API docs are right there, staring you in the face with the code you're reviewing.
See the DRM top-level, which gets turned into this document based on both the top-level and the code included by the top-level.
Posted Oct 23, 2020 20:55 UTC (Fri)
by rgmoore (✭ supporter ✭, #75)
[Link]
This sounds very reasonable. No documentation, no merge. The hard part is having the resolve to make it stick the first few times. Once everyone knows that's the rule and it will be enforced, they'll know to have the documentation done before the merge. Then the only hard part is keeping the documentation up to date as the code changes.
Posted Oct 18, 2020 23:29 UTC (Sun)
by deater (subscriber, #11746)
[Link]
only to find out it was a complete waste of time due to yet another gpio interface being added.
although I guess if the new interface has debounce support I won't have to spend a lot of time trying to convince students that sprinkling random usleep()s all over their code somehow counts as debouncing
5.10 Merge window, part 1
5.10 Merge window, part 1
Do not require (but do encourage) documentation for a proposed API but demand it in order to merge the API.
5.10 Merge window, part 1
5.10 Merge window, part 1
5.10 Merge window, part 1
5.10 Merge window, part 1
5.10 Merge window, part 1
Wol
5.10 Merge window, part 1
5.10 Merge window, part 1
If the newly added user space API is really **that** contentious, then by the time the maintainer is going to merge the changes, he asks for a final iteration with proper documentation.
5.10 Merge window, part 1