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

From: Ashley Blewer <[email-masked]>
Date: Mon, 7 Aug 2017 20:09:44 -0400

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

---

From: Katherine Frances <[email-masked]>
Date: Mon, 14 Aug 2017 14:47:18 +1200

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:
>
> 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.o
> rg/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-O
> rg/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.
>
> 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
>
>