Melpa: Clarify the MELPA requirements

[conao3]

When I suggested a docstring format, @rnkn blocked me in #6743.
I suggest to a package author to modify it to meet the requirements of MELPA to reduce the burden on MELPA reviewers since https://github.com/melpa/melpa/pull/6640#issuecomment-583911271.

I believe that package authors should follow the requirements of MELPA, but some people seem to take it lightly.
This discussion is essentially useless, and if MELPA don't point out docstrings, I think we need to change the MELPA's CONTRIBUTING.

[tarsius]

Suggesting that a package won't be added because its author wishes to stick to just one period between sentences is way extreme. Please don't do that. Ask the author to conform to the conventions but if they insist on sticking to some very minor idiosyncrasy, then let them.

It's not always clear where to draw the line but to me this falls very clearly in "in the end it doesn't matter at all" territory. This is very different from e.g. intending doc-strings starting with the 2th line so that they all align with the first. That is objectively a defect and needs to be fixed (it matters more what the documentation looks like in the documentation-viewer than it does in the source code).

[conao3]

Thanks @tarsius. How about @purcell and @riscy?

[riscy]

With respect to checkdoc, I don't tend to bother with the spaces-after-sentences lint because the variable that controls its behavior is unfortunately sentence-end-double-space. People don't realize (or care) that they're modifying checkdoc's behavior when they set this variable -- instead they just want to change how M-x fill-paragraph and M-x forward-sentence behave.

Also I consider it so minor that I would disable it if it were part of a pass/fail CI step (i.e. people can use two spaces or one), but that's just me. (I also mute a couple other checkdoc nags around proper nouns and the inaccurate verbs-wrong-voice list, just because these spew false positives and yield virtually no benefit, in my humble opinion.)

We could clarify CONTRIBUTING.org and soften the language a bit ("Please try in good faith to address all of the issues on the checklist; some are more important than others and could block your merge; use common sense"). I'm fine with writing something like this. There's also been a growing desire for improved CI, within which we could spell out exactly what linter nags are errors.

[purcell]

It's definitely good to clarify our requirements, and we should do this. I continue to fail at writing a "MELPA Maintainers' Handbook", sorry, though I'm steadily improving package-lint so that we can integrate checks properly in CI.

But at the same time, nobody should be giving feedback to elisp authors that they have not already seen given by actual MELPA maintainers. Our relationship with authors is very important, as is the deliberate, consistently friendly and welcoming response we try to give them. Sometimes this requires a degree of diplomacy, and that's hard to capture in a "MELPA requirements" doc. If contributors seem argumentative to you, or you have a difference of opinion with them, the maintainers can handle this and establish what's important. What I don't want to see here is friction between volunteer reviewers and contributors.

[conao3]

That's right.
A conflict between volunteers and Elisp package authors should have been avoided.

Volunteers can't make rules and temporarily ignore them.
That's the job of the MELPA maintainer, and the fact that only 5 people (@purcell, @tarsius, @milkypostman, @riscy, (@syohex)) do it today makes the situation difficult.

Anyway, I will just make an only suggestion and leave it to the MELPA maintainer.
I am sorry for showing such a conflict.

[milkypostman]

Please don’t hesitate to tag me or Purcell in any PR that require
maintainers to get involved. I don’t follow all day to day PRs closely but
try to watch for signs of conflict or issues that require my attention
(i.e., server issues.)

On Thu, Mar 12, 2020 at 04:06 Naoya Yamashita [e-mail]
wrote:

That's right.
A conflict between volunteers and Elisp package authors should have been
avoided.

Volunteers can't make rules and temporarily ignore them.
That's the job of the MELPA maintainer, and the fact that only 5 people (
@purcell https://github.com/purcell, @tarsius
https://github.com/tarsius, @milkypostman
https://github.com/milkypostman, @riscy https://github.com/riscy, (
@syohex https://github.com/syohex)) do it today makes the situation
difficult.

Anyway, I will just make an only suggestion and leave it to the MELPA
maintainer.
I am sorry for showing such a conflict.

—
You are receiving this because you were mentioned.

Reply to this email directly, view it on GitHub
https://github.com/melpa/melpa/issues/6746#issuecomment-598079621, or
unsubscribe
https://github.com/notifications/unsubscribe-auth/AAAJJMSVGIF42RAAFBRBPVDRHCQZBANCNFSM4LFNIXPA
.