Skip to content

feat: add submitter and reviewer guidelines #384

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

aschmahmann
Copy link
Contributor

This is an attempt at codifying some potential rules for governance of this repo, some are taken from how it seems we've been loosely governing over the last few years and others are newer.

While there's never really been a lot of time to engage on PRs here it's felt less recently. To that end I thought it'd make our lives (and those of the folks submitting codes) a little easier if we had a fairly permissive process with some guidance.

My understanding of the things I've added that are different from how things have been run so far are:

  • Having a probationary period: this is totally new, might be a good idea or bad, would like feedback)
  • Leaning more heavily into asking for specs: this has loosely been around for a while, sometimes we try and shove the spec into the text field if it's small enough 🙃. IMO asking for it even if its an evolving spec seems reasonable otherwise the code is effectively private since people can't discover what it's for.

I'll flag that I ran this by @hsanjuan for some sanity checking and IIUC he recommended just rubber stamping (i.e. first come first serve) anything in the 3 byte range and having a more proper review about the 1-2 byte range. Maybe this is a reasonable thing to encode as well.

Thanks in advance for any feedback and seeing if we can streamline things here a bit.

cc @rvagg @darobin @vmx

@@ -70,6 +70,8 @@ Selecting the appropriate tag helps maintain organization in the table and provi

### Adding new multicodecs to the table

#### Guidelines for submitters
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The guidelines here don't include anything about adding new categories. I figured that happens much less frequently and we could look at that once we have something we're happy with here.

For reviewers of new codes please consider:
- [ ] Does the code fit within the relevant tagged category?
- [ ] Is this code needed or could it be served by an existing code?
- [ ] Is the byte size of the requested code suitable or should it be higher?
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- [ ] Is the byte size of the requested code suitable or should it be higher?
- [ ] Is the byte size of the requested code suitable or should it be higher? (i.e. `0x7f` and below are the single-byte range, up to `0x3fff` is the two-byte range; you should have good case for occupying lower ranges of the table)

or something like this because I suspect a lot of people have no idea what we're talking about when we refer to this

@rvagg
Copy link
Member

rvagg commented Jun 25, 2025

This is mostly fine I think, and I agree on being fairly liberal, but there's a couple of extra criteria that we tend to apply these days, regardless of where in the table they fall:

tbh though the biggest bottleneck in getting things processed here is just the contextual knowledge required to even sanity check that a new entry even makes basic sense. A reviewer needs to read an entry, often do some Googling or following links and doing some reading to get a grip on the domain. Just basic stuff usually, "is this even a hash function?", "don't we have an entry that smells like this? are they the same thing?". This requires reviewers to slice out time to make the mental leap to engage just to avoid spam and duplicates.

Copy link
Member

@vmx vmx left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm unsure about the probation period. If I would submit something I would find it difficult to "prove" that it's really used. Maybe it's just a small niche project and you don't even have the time for creating metrics, or you don't even really know your users (which is often the case for open source projects).

I can see that addition something like this would make sense in low byte ranges, where there is disagreement on whether it should be added or not. But if someone puts something in e.g. the 3 bytes range and hardly anyone is using it, I wouldn't be concerned.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants