Subject: Re: [Cellar] Contributing recommendations (for new users) (according to me)

From: Kieran O Leary <[email-masked]>
Date: Fri, 27 Jul 2018 11:45:22 +0100

Sorry for the bump, but I wonder if there is a value in adding some
contributor guidelines to the github pages?
I'm about to start a review of the Matroska spec and I was looking for
some guidance on how best to approach it. Ashley's guidance is pretty
much exactly what I needed.

-Kieran O'Leary
IFI Irish Film Archive.

On Mon, Aug 14, 2017 at 3:47 AM, Katherine Frances <[email-masked]> wrote:
> Hey Ashley,
>
> Thanks for this timely post. Dave Rice contacted me some months ago to help
> with the specs, but new job & general life responsibilities got in the way.
> So it's a useful mail for me, hopefully I can dive into some spec work in
> the next while!
>
> Cheers, K
>
>
> On Tue, Aug 8, 2017 at 12:09 PM, Ashley Blewer <[email-masked]>
> wrote:
>>
>> Hi CELLAR,
>>
>> I've talked to a couple of lurkers on this list that want to get involved
>> but don't know where to start. Here are a few guidelines just based on my
>> experience:
>>
>> EBML, Matroska, FFV1, FLAC:
>>
>> Review for inconsistencies: typos, contradictions, ambiguity in the
>> documentation. So just picking one of the specs and giving it a good review
>> is incredibly helpful. The Matroska spec needs a lot of work here, as it is
>> written in a colloquial manner inconsistent with "standards-style" language.
>> There's plenty of work to do before that can really start to matter, but
>> it's a good starting point to get familiar with the docs. That's what I've
>> started doing. This can be brought up on the CELLAR list (preferred),
>> brought up as a Github issue for the specification, or a pull request can be
>> sent to change the codebase and a conversation can happen there.
>>
>> Specs can be reviewed purely with an eye towards compliance with RFC2119
>> (https://www.ietf.org/rfc/rfc2119.txt): Are these words being used
>> appropriately? Is there something listed as a SHOULD but should be a MUST?
>> Is the word being used but not capitalized, and so recommendation is being
>> unintentionally implied, and the word should either become full-caps or
>> changed? This kind of tedious-work passthrough is a good way to familiarize
>> yourself with one of the documents with plans to analyze more specifically
>> later.
>>
>> EBML:
>>
>> EBML is in a more advanced stage than others, but can still use more eyes
>> for general review. This initial review of EBML is helpful as a guideline
>> for what to look for and how to look for it:
>> https://mailarchive.ietf.org/arch/msg/cellar/Mfj44tK1gyfqjU3Uu1tI5fMovtk
>>
>> Matroska:
>>
>> I've been just doing that general work of cleaning up language and looking
>> for inconsistencies. Matroska docs are VERY long and helpful for users but
>> less "specification standard". Lots of eyes here would be helpful since
>> there is a lot of ground to cover. There's a handful of issues on the Github
>> tracker (https://github.com/Matroska-Org/matroska-specification/issues) but
>> not sure how many are suitable for novices. A review of the Matroska spec
>> that seeks for any redundant or conflicting information is a worthwhile
>> endeavor. We are very fortunate to have Moritz and Steve as active members
>> and contributors to this group. :)
>>
>> FFV1:
>>
>> FFV1 is a little harder to break into, but there was a review by Derek
>> Buitenhuis posted to the CELLAR list on July 28 pointing out questions (
>> https://mailarchive.ietf.org/arch/msg/cellar/qItSPq06vc9MaxsZFPJ3GmREsr4 ).
>> Work towards reviewing and deciding what can be done with this can be used
>> as a basis for where to start looking. Again, just searching for typos and
>> contradictions and noting them is important.
>>
>> FLAC:
>>
>> FLAC has some issues on the issue tracker that could be worked on:
>> https://github.com/privatezero/flac_markdown/issues
>>
>> Issue #25 is of note -- when I have more time, I'll dig into that one a
>> bit more and make new tickets. It seems like the code and the specification
>> have diverged slightly in terms of what things are named, and the spec
>> should be updated to reflect what is in the source code. That's some fun
>> ("fun") digging-around work that takes time but isn't intrinsically hard or
>> requires expertise in the languages. The original ticket is about getting
>> anchors to work, there's some discussion in the ticket about what to do
>> about that.
>>
>> In general, FLAC needs a more permanent Github home that isn't Andrew's
>> personal Github (as reported by the IETF meeting notes -- unsure what kind
>> of nudging should be done here), and more nudging on the flac-dev list about
>> any questions in the spec that need explaining. It'd be good to get a closer
>> feedback loop with the FLAC crew, which can be done by bringing up issues on
>> both listservs. Not that much work has been started on FLAC yet so it's open
>> terrain.
>>
>> Overall, just reading and questioning the specifications is valuable work.
>>
>> If you are not very familiar with Github or are generally unsure how to
>> contribute there, please feel free to contact me off-list and I'd be happy
>> to explain/clarify questions.
>>
>> My best,
>>
>> Ashley
>>
>> _______________________________________________
>> Cellar mailing list
>> [email-masked]
>> https://www.ietf.org/mailman/listinfo/cellar
>>
>
>
> _______________________________________________
> Cellar mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/cellar
>

---

From: Michael Richardson <[email-masked]>
Date: Fri, 27 Jul 2018 11:44:03 -0400

> contributor guidelines to the github pages?

What exactly are you thinking about?
Are you thinking about text formatting issues?
The IETF NOTEWELL applies, as far as all legal issues.
See: https://www.ietf.org/about/note-well/

We should probably pull it into the README.md, like:
    https://github.com/anima-wg/voucher

does.

    > much exactly what I needed.

Thank you for the review.
Please post your review as email to this email list.

-- 
Michael Richardson <[email-masked]>, Sandelman Software Works
 -= IPv6 IoT consulting =-

---

From: Kieran O Leary <[email-masked]>
Date: Tue, 31 Jul 2018 11:16:34 +0100

Hi Michael,

> What exactly are you thinking about?

I was thinking more along the lines of what Ashley mentioned earlier
in the thread. How to contribute to the project. Specifically, I
wanted some guidance on what kind of reviews might be needed,
depending on your knowledge level, and how to deliver the feedback
(github/cellar)

> Please post your review as email to this email list.

Will do!

Best,

Kieran.