I want to start a discussion here of the guidance we want to give to package
authors on the tags they assign in zkg.meta, to ensure people have a chance to
chime in, and we start-out with the benefit of multi-perspective group process,
so we reach for the best result.
My proposal is just to articulate principles for good tag selection, to rein in
the existing scattershot we've seen so far, by giving the authors guidance on
what we want to see. I think we need to do this, to counteract that nearly
everyone takes their guidance from what they see the people before them have
done. If bad habits occurred and are allowed to persist, people will dutifully
adopt those bad habits.
I posit that: the ideal set of tags will provide matches with queries of the
form: "Has a plugin for X already been coded?" And also matches with some of
the relevant queries for: "What other plugins have been coded for aspect Y?"
Find the words by filling in the sentences: "I implemented X." and "I
implemented an instance of Y." For Y, use the plural (indicators, scanners,
scripts) except when only the singular makes sense.
Use the hyphen where punctuation is needed. Never use underscore.
Don't add "analyzer" nor "protocol" nor "plugin" as a suffix.
Don't mention bro or zeek. These are all Bro/zeek analyzers and plugins.
The ideal set of tags can also include one that is perhaps unique to this
package (but not four or five that are unique to this package). This is as a
moniker, so that saying "go look at fizzamajig" should lead, by following the
fizzamajig tag, to what you intended the listener to see.
Conversely avoid banal tags. If you write a piece of software, nonetheless "a",
"piece", "of", and "software" are all bad tags.
Capital letters should be a rarity, i.e. in DoS because dos to many eyes,
immediately connotes a pre-Windows Microsoft operating system. att&ck is fine
punctuated that way, and PostgreSQL and all the CVE are reasonable to
capitalize. SSL, TLS, TCP, PKI, UPnP, and EternalBlue are stalking-horses, to
consider, while we reach consensus, whether we are better off just lowercasing
where the capitalization is not essential. If in doubt, just use alllowercase.
Tags function quite well in alllowercase, and that is what most people have
done.
If anyone uses the hyphen-form for a word, then everyone shall use the
hyphen-form for consistency. It does often increase readability, and is a small
price for the increase of understanding in the portion of our community which
it benefits.
Anyone who disagrees with any of these details, PLEASE do chime in as I only
seek that we we reach for the best result, not that we we reach for my idea of
what the best result is.
Anyone who has additional heuristics of goodness to add, also chime in with
them. We'll probably, after consensus, enact change by sending some PRs to a
few packages to unify them more. I did a sort of census last evening. Of 273
tags used, I would banish 51 of them, and revise the punctuation or
capitalization of 15 others.
- Duffy O'Craven
_______________________________________________
zeek-dev mailing list -- zeek-dev@lists.zeek.org
To unsubscribe send an email to zeek-dev-le...@lists.zeek.org
