[Zeek-Dev] adding credits to the schema for package metadata

[Jon Siwek]

On Fri, Jan 4, 2019 at 1:48 PM Vern Paxson <vern at corelight.com> wrote:

> > It's maybe something packages.zeek.org would show, but I don't see how
> > that would be better than looking at the "contributors" stats already
> > compiled by GitHub from author info encoded directly into git commits.
>
> The problem with those stats is (1) they're removed from the Web UI,

Could just link to it or else gather stats ourselves for display there
if it's important enough.

> (2) they're not in a coherent form.

That seem like it's up to the committer to get right -- if they don't
care enough to use coherent git user information, then that seems like
an indication that they don't care how others recognize their
contributions.

> The git commits don't necessarily identify the author like they
> would want for public recognition

But that's completely under their own control to change however they want.

> can be missing co-authors for instances

There's a common git convention for co-authors they should then use:

https://help.github.com/articles/creating-a-commit-with-multiple-authors/

> can make it unclear whether a given git contributor merits public credit.

I think I get that point, but who gets chosen still seems arbitrary,
which is why I feel the focus should be on getting the git data
accurate since that can speak for itself.  But I can see how it may be
important to have alternate credit mechanisms in cases where
historical git data is not correct and can't be changed.

> > Alternatively, why would it help to have more free-form "credit"
> > information specifically in the metadata file versus in README,
> > CONTRIBUTORS, or AUTHORS files, which are already a common convention
> > in open-source projects?
>
> There are 3 possible advantages.  (1) We know where to look for it.
> (2) The Web UI can display it.  (3) Contributors can know to think about
> it up-front in terms of what ought to be displayed publicly, which could
> be a bit different than what might go into one of those files.

(1) and (2) are just about choosing a standardized location and
documenting it.  That can be anywhere, but I was more just pointing
out that while adding it to the package metadata does work, it's also
currently only hosting data that serves a functional purpose for the
command-line tool.  Credit information would not be used in any
functional way by the command-line tool, so that's why I was
suggesting alternatives that would put this issue more in the "good
conventions/practices for open-source project management" camp rather
than anything specific to bro-pkg.  (Thinking it's generally a good
idea to limit our involvement in how people choose to maintain their
own work).

> Can we make it non-optional by having it be part of the contribution
> process, just like (I believe) the need to clarify licensing currently is?

It could, but I'd say it's not great to add requirements to the
contribution process unless really needed.  We're also not going to be
able to enforce whether people keep that field updated properly and
begs what to do about existing packages that don't promptly add a
credits field to their metadata.

I'm still cool with documenting an optional "credits" field for the
package metadata, but just making sure, given all the caveats, that it
solves the problem sufficiently?  I'd probably word the docs like:

"If you have particular requirements or concerns regarding how authors
or contributors for your package are credited in public listings, you
may explicitly provide the text that should be used to name or
describe such people in this field".  And then also provide your
example.

- Jon