Draft: Docs/governance #2307
Draft: Docs/governance #2307
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
@blocknote/ariakit
@blocknote/code-block
@blocknote/core
@blocknote/mantine
@blocknote/react
@blocknote/server-util
@blocknote/shadcn
@blocknote/xl-ai
@blocknote/xl-docx-exporter
@blocknote/xl-email-exporter
@blocknote/xl-multi-column
@blocknote/xl-odt-exporter
@blocknote/xl-pdf-exporter
commit: |
nperez0111
left a comment
nperez0111
left a comment
There was a problem hiding this comment.
Very well-thought out @woutervroege, I really like this structure. This is a good point to aim towards, I'm interested to hear your thoughts on the specific implementation of this
There was a problem hiding this comment.
There is a thing called CODEOWNERS which may be relevant to this @woutervroege
There was a problem hiding this comment.
@nperez0111 Thanks! Where can I find this file? Doesn't seem to be in the repo.
There was a problem hiding this comment.
Oh we don't have one, it is just a standard: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
There was a problem hiding this comment.
This is great, I think it aligns a lot with how we want to work and more importantly, gives transparency to the community. Left some inline comments, and general thoughts here:
Size
It's quite the collection of documents. While I understand where they all come from, I have two concerns:
- Maintainability: More docs -> more difficult to maintain.
- Usage / inclusiveness: I'm afraid that the more governance docs we write, less will be read / used. Related; it might also hold people who are not as proficient in English back in contributing / engaging with the project. We could also mitigate this somewhat by keeping the most actionable items in the root of the project, while keeping background processes in a separate dir
! I also feel that at this moment there's quite some duplicate info (I think especially the flows / rfc / roles are described in multiple places)
Rollout strategy
Our current working process is somewhat unstructured. I think we should consider the trade-off between first adopting these processes (gradually?) internally, and then publishing this, instead of the other way around.
Risks I see with the latter:
- We largely fail to follow the processes described, turning the docs into "fake transparency" which is worse than having no transparency at all
- Or, the other way around; we relentlessly try to follow the processes but find it difficult to admit they don't work for us (yet)
Company
I think we're not addressing the elephant in the room that people might be curious about; how is the project funded, what's the relationship between the business and open source project, etc. I think this is the no. 1 thing people are curious about that gives them trust in the project or not, and also to judge the "value" / trustworthiness of the other documents. We can also explain a bit more about SLAs for sponsors (prioritized bug reports), etc.
Hope this helps! Curious what you think!
| - **Status**: Idea | Draft | Accepted | Rejected | Revision Requested | ||
| - **Author(s)**: <name / handle> | ||
| - **Champion**: | ||
| - **Created**: |
There was a problem hiding this comment.
created and last updated can be viewed in git, maybe remove this (or at least "last updated")
|
|
||
| ### Responsibility | ||
|
|
||
| - **Maintainers** are responsible for technical triage and classification |
There was a problem hiding this comment.
I think this could also be the other way around where Product leads technical triage and classification, and maintainers can help with more technical issues and provide input about technical impact etc.
There was a problem hiding this comment.
(after reading on); For highly technical issues your approach makes sense (maintainers lead classification in p0-p3).
However, I think what we're missing:
- if issues are easy to reproduce and understand, prioritization doesn't require technical input
- many GH issues are feature-requests
- filed issues are of mixed quality, some might need more input than initially given
- ...
etc. Point is; there's probably quite some work around managing issue lifecycle that's not deeply technical per se
|
|
||
| Pull requests that introduce significant changes without prior discussion may be redirected or closed. | ||
|
|
||
| --- |
There was a problem hiding this comment.
I think we should separate the technical stuff below to separate guides
| - Ability to act as Product Owner (PO) for execution within accepted RFC scope | ||
| - Ability to establish and facilitate regular operational processes (such as bug triage) to support maintainers and contributors | ||
|
|
||
| Product management does not make technical decisions, does not override maintainer or TSC authority, and does not bypass the RFC or review process. Product management may facilitate processes such as bug triage, but technical classification and severity decisions remain the responsibility of maintainers. Individuals may hold multiple roles; decision authority depends on the role being exercised. |
There was a problem hiding this comment.
You're introducing the term "Product management" under the section about TSC.
I think that if these are purely clarifications about PM vs. TSC, I think they should be more succint. If they're here to describe the role of PM, it should move to the section below.
|
|
||
| ## Overview | ||
|
|
||
| BlockNote is an open-source project stewarded by the founding team with the goal of growing into a contributor-led ecosystem over time. Governance is designed to balance long-term technical integrity, transparency, and sustainability while remaining lightweight at the project’s current scale. |
There was a problem hiding this comment.
I'm not sure "growing into a contributor-led ecosystem" is an explicit goal at this moment (or we should further clarify it). Point in case; if there's a profitable organization (like OpenBlocks) supporting it, is it contributor led?
| ``` | ||
|
|
||
| This pipeline is risk-based: the higher the impact or precedent, the more explicit the decision-making. |
There was a problem hiding this comment.
What does this mean exactly? Does it mean that for smaller things, we don't "need" to follow the above pipeline? If so, good to make explicit
There was a problem hiding this comment.
from reading further, I think my assumption is correct (but maybe still good to revisit the phrasing here)
| Ideas and needs can originate from many places: | ||
|
|
||
| - Community contributors | ||
| - Enterprise or public-sector users |
There was a problem hiding this comment.
Maybe better to name this
- "Sponsored clients"
- or more extensive "Sponsored clients (e.g.: Startups, Enterprise or Public-sector)"
| @@ -0,0 +1,27 @@ | |||
| # Mission | |||
There was a problem hiding this comment.
will review this doc later
|
|
||
| An RFC is expected to have a **champion** once it is ready for formal consideration. | ||
|
|
||
| The champion may be the original author or another volunteer. Their responsibility is to: |
There was a problem hiding this comment.
is it needed to have both "author" and "champion"? seems overkill. What about a single "Owner" role?
| @@ -0,0 +1,214 @@ | |||
| # Team Operations | |||
There was a problem hiding this comment.
I like the clarity / actionability of this doc!
Summary
Rationale
Changes
Impact
Testing
Screenshots/Video
Checklist
Additional Notes