Skip to content
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

Getting Multibase ready for IETF review (align with IANA terminology and registry governance style) #109

Merged
Show file tree
Hide file tree
Changes from 23 commits
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
12705bb
first-stab-at-closing-4
Jul 4, 2023
b7307ea
second-stab-thanks-to-@aarongoldman
Jul 4, 2023
e380b70
typo
Jul 4, 2023
5c7594a
remove confusing 0xe7 reference for now
Jul 4, 2023
b0bf557
third attempt to clarify that base256emoji as codepoint
Jul 4, 2023
d451436
typo fix (thanks rvagg)
bumblefudge Jul 5, 2023
a39f8ac
tab-aligning tables
Jul 5, 2023
a1b75a5
clarify unicode versus utf-8 + fix table
Jul 5, 2023
9d69e19
future-proof collision-protection against single-byte multiformats
Jul 6, 2023
e814396
update readme language
bumblefudge Jul 18, 2023
e79d6d8
align status column with iana terms
bumblefudge Jul 18, 2023
d875325
add issue templates to the repo
bumblefudge Jul 18, 2023
c3dbd70
refine issue templates
bumblefudge Jul 18, 2023
e071bc1
refine issue templates
bumblefudge Jul 18, 2023
f07376c
refine issue templates
bumblefudge Jul 18, 2023
f7c29ce
refine issue templates
bumblefudge Jul 18, 2023
3e8ce2b
multibase.csv typo
bumblefudge Jul 21, 2023
dafe60b
csv typos
bumblefudge Jul 21, 2023
b9ca042
csv typos
bumblefudge Jul 21, 2023
52b3c06
undo hard-wrapping of lines per vmx request
bumblefudge Jul 24, 2023
be3ab37
embarassingly walking back all my wierd changes
bumblefudge Aug 8, 2023
caee143
good catch @vmx
bumblefudge Aug 9, 2023
ff1fe45
good catch @vmx
bumblefudge Aug 9, 2023
075fa01
address VMX's comments and refine ### Reserved Terms section
bumblefudge Aug 14, 2023
873440d
rename code to char and flip column order
bumblefudge Aug 14, 2023
bb5ae08
Merge branch 'master' into hotfix/clarify-code-column-and-intro-to-match
bumblefudge Aug 14, 2023
ccca39b
fix merge conflict artefacts
bumblefudge Aug 14, 2023
d773cd8
fix merge conflict artefacts take 2
bumblefudge Aug 14, 2023
4c51364
less required fields in .github/ISSUE_TEMPLATE/BUG-REPORT.yml
bumblefudge Aug 22, 2023
432b270
less required fields in .github/ISSUE_TEMPLATE/BUG-REPORT.yml
bumblefudge Aug 22, 2023
e0f3632
typo in README.md
bumblefudge Aug 22, 2023
d20580d
require registrants to volunteer as change controller and PR opener
bumblefudge Aug 22, 2023
6eba60f
remove new implementation template for now
bumblefudge Aug 22, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions .github/ISSUE_TEMPLATE/BUG-REPORT.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
name: "Bug Report - documentation or registry"
description: Report possible bugs in multibase spec, process docs, and/or the multibase registry.
title: "🐛 [DOC/PROCESS BUG] - <title>"
labels: [
"bug"
]
body:
- type: textarea
id: description
attributes:
label: "Description"
description: Please enter an explicit description of your issue,
placeholder: Short and explicit description of your incident, ideally with commit-specific link to lines
validations:
required: true
- type: input
id: reprod-url
attributes:
label: "Reproduction URL"
description: Please enter your GitHub URL to provide a reproduction of the issue
placeholder: ex. https://github.com/multiformats/multibase/
validations:
required: true
bumblefudge marked this conversation as resolved.
Show resolved Hide resolved
- type: textarea
id: context
attributes:
label: "Context"
description: Please provide additional context
placeholder: "Context or external links needed to explain the possible mistake"
validations:
required: true
bumblefudge marked this conversation as resolved.
Show resolved Hide resolved
55 changes: 55 additions & 0 deletions .github/ISSUE_TEMPLATE/NEW-IMPLEMENTATION.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
name: "Interest in Implementing - New Multibase Library or System"
description: Express interest in possible new multibase library or system
Copy link
Member

Choose a reason for hiding this comment

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

From the README:

If you'd like to switch a project over to multibase, whether by creating a new multibase implementation or building on one of those listed above, please file an issue in this repository using the "Interested in implementing" issue template.

This isn't really actionable and I'm unsure what we're supposed to do with these issues. Just a nod and and ignore? I'd like these to be actionable and not leading to cruft in the issue tracker since we already have a tendency toward cruft-buildup.

I think the purpose here might be to get a new implementation/library/system onto a list somewhere, can we just shunt people to open a pull request to add their thing? The "express interest" only really tells me that the issue opener is going to open a new issue telling us what they have in their head, which may be awesome, or may be terrible, but it's not really actionable without a thing or an explicit question--which is fine, but this isn't a template for a question.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Would this be better handled by a GH "Discussion"? TBH I wanted an "expressed interest" tracker somewhere for IETF purposes, because the perennial question of standardization is "for whom is this actually useful outside of the PLN/IPFS community that spawned it?"...

Copy link
Contributor Author

@bumblefudge bumblefudge Aug 22, 2023

Choose a reason for hiding this comment

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

In the interest of not holding up this PR, I have just cut that template for now and will open a new PR adding it as a Discussion template.

I only realized just now that discussion templates are also a thing! Separate PR incoming.

title: "📚 [NEW PROJECT] - <title>"
labels: [
"ideation"
]
body:
- type: input
id: project-name
attributes:
label: "Name of Project"
description: Name this library or system
placeholder: (language-)Multibase(-usecase), for example
validations:
required: false
- type: checkboxes
attributes:
label: "Have read contributing"
description: I have read the [contributing](https://github.com/multiformats/multiformats/blob/master/contributing.md) document
options:
- label: I read it!
validations:
required: true
- type: textarea
id: problem_statement
attributes:
label: "Description of parsing, sniffing, or encoding problem solved"
description: Please describe the problem solved by a new multibase library or system depending on multibase codecs
placeholder: Feel free to provide links for context and use-case descriptions, and how this problem is not solved by existing multi-formats entries or mini-registries
validations:
required: true
- type: textarea
id: prior_art
attributes:
label: "Description of relevant prior art and status quo"
description: Please describe relevant prior art and how this is use-case functions today
placeholder: Links welcome
validations:
required: true
- type: textarea
id: solution_and_rationale
attributes:
label: "Proposed solution and rationale"
description: Please describe at a high level what you are exploring building and current open research questions
placeholder: Detail welcome
validations:
required: true
- type: textarea
id: questions
attributes:
label: "Any further questions or requests"
description: Anything else you'd like to ask the maintainers or community?
placeholder: ok to leave blank!
validations:
required: false
69 changes: 69 additions & 0 deletions .github/ISSUE_TEMPLATE/NEW-REGISTRATION.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
name: "New Registration"
description: Express interest in registering a new encoding
Copy link
Member

Choose a reason for hiding this comment

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

If would also like to reserve a prefix for compatibility, please file a separate issue in this repository using the "New Registration" issue template.

This one's a little better, but I'd still prefer this in PR form rather than this asking us to do the PR for them; I'm not really a user of github issue templates (nor particularly a fan! I did my time in JIRA hell already so I can do without the extreme structure), do we have the tools to shunt people toward a PR with all of these things filled out there?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Will rework the semantics so that it's more of a placeholder. Maybe something like "open this issue so we can give you timely feedback before you start, but please open a draft PR soon and work there until you can close the issue you just opened" would work?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Does the insertion of this checkbox make it explicit enough?

Copy link
Member

Choose a reason for hiding this comment

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

Yeah, I guess -- what I'd like to avoid here is a collection of poorly maintained opened issues with no clear path to getting them closed. If we permission people opening unactionable issues, then we can't take action and have no clear path to closing them.

I think it's fine to have issues opened flagging intent to register, but we have to acknowledge that there's a limit to how long those will be held.

title: "📚 [NEW REGISTRATION] - <title>"
labels: [
"Registration"
]
body:
- type: input
id: encoding-name
attributes:
label: "Name of encoding"
description: Name this library or system
placeholder: acronyms and abbreviations are fine
validations:
required: false
- type: checkboxes
attributes:
label: "Have read contributing"
description: I have read the [contributing](https://github.com/multiformats/multiformats/blob/master/contributing.md) document
options:
- label: I read it!
validations:
required: true
- type: checkboxes
attributes:
label: "Have checked table"
description: I have reviewed the [multiformats mega-table](https://github.com/multiformats/multicodec/blob/master/table.csv) to assess viable sub-namespace for a registry if applicable
options:
- label: I read it!
- type: input
id: codepoint
attributes:
label: "Proposed codepoint"
description: Please put here the prefix in the target encoding. By tradition, the highest binary value in the encoding alphabet works well and has a built-in mnemonic if it doesn't conflict with any other entries
placeholder: x
validations:
required: true
- type: input
id: varint-value
attributes:
label: "Proposed varint value for registration in multiformats"
description: Please put here the UTF-8 value that corresponds to that target encoding, for inclusion in the multiformats table, formatted as an [unsigned varint](https://github.com/multiformats/unsigned-varint)
placeholder: See mf/unsigned-varint
validations:
required: true
- type: textarea
id: use-case
attributes:
label: "use-case"
description: Please describe the possible use-cases where this additional codec would be helpful, where this encoding is used currently in the wild, etc.
placeholder: Feel free to provide links for context and use-case descriptions
validations:
required: true
- type: textarea
id: specification
attributes:
label: "Description of relevant prior art and status quo"
description: Please describe relevant prior art and, if already specified in a static public document, the algorithms and configurations needed to deterministically encode/decode
placeholder: Links welcome
validations:
required: true
- type: textarea
id: solution_and_rationale
attributes:
label: "Proposed solution and rationale"
description: Please describe at a high level what you are exploring building and current open research questions
placeholder: Detail welcome
validations:
required: true
5 changes: 5 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
blank_issues_enabled: true
contact_links:
- name: Protocol Labs Vulnerability Disclosure Team
url: mailto:[email protected]
about: Please do NOT open issues related to security of implementations or spec here without contacting the IPFS security team first.
Loading