svn commit: r476670 - in head/devel: . rubygem-solve

[Adam Weinberger]

On Thu, Aug 9, 2018 at 6:30 AM Mark Felder <feld at feld.me> wrote:
>
>
>
> > On Aug 8, 2018, at 17:18, Adam Weinberger <adamw at adamw.org> wrote:
> >
> > On Wed, Aug 8, 2018 at 3:57 PM Ryan Steinmetz <zi at freebsd.org> wrote:
> >>
> >>
> >> On (08/08/18 23:34), Mathieu Arnold wrote:
> >>>>> Ryan,
> >>>>>
> >>>>> You've just added a number of ports with uninformative pkg-descrs, and
> >>>>> unhelpful COMMENT strings. These aren't merely formalities. Users
> >>>>> should be able to read the pkg-descr and understand if it's the right
> >>>>> package for them, and COMMENT is the first target for searches.
> >>>>> Please, go back over them and, at the very least, expand the pkg-descr
> >>>>> files with more information. As a general rule, pkg-descr should NEVER
> >>>>> be the same text as the COMMENT.
> >>>>
> >>>> Adam,
> >>>>
> >>>> These are the description strings from authors of the code.  They came from
> >>>> either rubygems.org and/or the gem source repository.  For example, in the
> >>>> case of rubygem-solve:
> >>>>
> >>>> https://rubygems.org/gems/solve
> >>>>
> >>>> https://github.com/berkshelf/solve
> >>>>
> >>>> If you have any specific things you would like to see added to any of the
> >>>> individual ports, please let me know.
> >>>
> >>> pkg-descr must contain sentences, something that can be read. It must at
> >>> least be two lines long, so that it is descriptive enough.  The fact
> >>> that upstream is crappy does not mean you can put he same crap in the
> >>> ports tree.  It is your job as committer to make sure that ports conform
> >>> to our policies and requirements.  If upstream does not provide a better
> >>> decription, create one, basd on your knowledge of the software.
> >>
> >>
> >> https://svnweb.freebsd.org/ports/head/devel/p5-Data-Serializer-Sereal/pkg-descr?revision=401986&view=markup
> >>
> >> https://svnweb.freebsd.org/ports/head/net/rubygem-epp-client-afnic/pkg-descr?revision=380380&view=markup
> >>
> >> https://svnweb.freebsd.org/ports/head/net/rubygem-epp-client-smallregistry/pkg-descr?view=markup
> >>
> >> https://svnweb.freebsd.org/ports/head/net/rubygem-epp-client-secdns/pkg-descr?revision=380380&view=markup
> >
> > Ryan, what exactly is it that you're arguing in favour of here? All I
> > requested was for you to please add some helpful information in the
> > descrs where possible. So far you've argued that uninformative descrs
> > are okay as long as you copied it from someone else, and that
> > uninformative descrs are okay because you're not the only one who does
> > it.
> >
> > I'm trying to get people on board with fixing what's been an ongoing
> > problem in our ports. You've agreed with the problem, but not the
> > solution. If you have another solution to terse descrs that's
> > different from putting more information in descrs, I'm eager to hear
> > it.
> >
>
> Adam, please stop. You cannot honestly expect committers to invent descriptions for ports that have zero documentation. I have plenty of ports myself that only exist in the tree because I had to chase dependencies for the software I intended to port. Most of these are libraries that have non-descript or "too-clever" names and of which I have no idea what their function is. It is not my responsibility nor the responsibility of any committer to fix this problem.

Okay, heard. I'll drop it. I don't think that copying and pasting the
first sentence or two of the documentation that every module/library
provides on the WWW is onerous, but if it's not our responsibility
then it's not our responsibility.

# Adam


-- 
Adam Weinberger
adamw at adamw.org
https://www.adamw.org