garydgregory commented on PR #324:
URL: https://github.com/apache/commons-dbutils/pull/324#issuecomment-2488722121
Hello @strangelookingnerd
Thank you for the thoughtful reply.
The README, CONTRIBUTING, and other files are generated when we create a
release candidate. These files are out of date, so I'll offer my apologies for
that. I just pushed re-generated versions of the README and CONTRIBUTING files.
Let me offer you different POVs:
- This is a PR, it needs to be minimal, what JUnit calls a "best-practice"
is really a style change from my POV and is not as important as maintainer time
and sanity.
- If a maintained wants to, later, make all these noisy changes, then can
do so, but, IMO it doesn't belong in a PR. If this project used RTC instead of
CTR, then we'd have no choice, but we use CTR, so here we are ;-)
- A class Javadoc on a test class is important for several reasons IMO, and
this is what I do all the time: I am navigating test classes, I hop into a
"TestFoo" class and I want to jump to the subject class "Foo", all I have to do
in my IDE (Eclipse), is click on the class name in the Javadoc comment that
says "Tests {@link Foo}." and I'm there.
- Using the link tag makes it obvious to the reader what is under test, for
example, "Tests {@link Foo} when Bar has been fiddled".
- The class Javadoc also offers a placeholder for other comments when a
class may have dependencies on some interesting environment like "Uses Docker
for this and that", or "Temporarily sets environment variables this and that".
- Having just a minimal Javadoc offers a place for maintainers and
contributors to say something. I want to encourage: "Oh, yes, that's the place
I should add my tidbit of knowledge about testing this class." As opposed to:
"Well, there is no Javadoc, since no one seems to care about documenting how
this works, I won't say anything either about the bell and whistle."
- It doesn't matter what tool is used (well, it matters if you use something
that uses AI-generated stuff based on copyrighted material or sources that are
incompatible with the Apache license), what matters is the PR and the changes
it contains. I expect contributors to review their PRs, magically generated or
hand-crafted. As a maintainer, I must review each line of code (XZ Utils). It's
only fair to ask contributors to do the same ;-)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
