diff --git a/.github/RFC_TEMPLATE.md b/.github/RFC_TEMPLATE.md new file mode 100644 index 0000000000..6edf309404 --- /dev/null +++ b/.github/RFC_TEMPLATE.md @@ -0,0 +1,109 @@ +# RFC Template + +- **Status**: Idea | Draft | Accepted | Rejected | Revision Requested +- **Author(s)**: +- **Champion**: +- **Created**: +- **Last Updated**: +- **Related**: + +--- + +## 1) Summary (2–5 sentences) + +What is being proposed and why? Keep this understandable to non-specialists. + +--- + +## 2) Problem & Motivation + +- What problem are we solving? +- Who is affected? + +--- + +## 3) Goals & Non-Goals + +### Goals + +What outcomes should this RFC achieve? + +- … +- … + +### Non-Goals + +What is explicitly out of scope for this RFC? + +- … +- … + +--- + +## 4) Proposed Approach (High-level) + +Describe the proposed approach at a level suitable for review: + +- Key idea(s) +- Expected behavior changes (if any) +- Any public API changes (if any) + +--- + +## 5) Trade-offs & Alternatives + +### Trade-offs + +What are the downsides or costs of the proposed approach? + +### Alternatives + +What alternative approaches were considered, and why were they not chosen? + +--- + +## 6) Impact + +### Compatibility + +Are there breaking changes? Is migration required? + +### Performance + +Any expected performance impact? + +### Security / Privacy + +Any security or privacy implications? + +### Maintenance + +Expected long-term maintenance cost or complexity. + +--- + +## 7) Open Questions + +- … +- … + +--- + +## (Optional) Implementation Notes + +Only include if it helps reviewers: + +- rollout/migration sketch +- testing strategy +- rough milestones + +--- + +## Decision (TSC) + +Filled in by the TSC when decided. + +- **Decision**: Accepted | Rejected | Revision Requested +- **Rationale**: +- **Date**: +- **Recorded by**: \ No newline at end of file diff --git a/BUGS.md b/BUGS.md new file mode 100644 index 0000000000..d78d87cc1e --- /dev/null +++ b/BUGS.md @@ -0,0 +1,151 @@ +# Bug Reporting & Triage + +This document explains how bugs are reported, triaged, and resolved in the project. + +The goal is to: + +- Make it easy for users to report issues +- Ensure bugs are handled consistently and transparently +- Keep technical decision-making with maintainers while enabling support from Product and the community + +--- + +## What Is a Bug? + +A bug is behavior that: + +- Is incorrect or broken compared to documented or intended behavior +- Regresses previously working functionality +- Causes crashes, data loss, or security issues + +Requests for new features or behavior changes are NOT bugs and should be raised as ideas or proposals instead. + +--- + +## Reporting a Bug + +Anyone may report a bug. + +Please open a GitHub Issue and select 'Bug Report'. The template provided will require: + +- A clear description of the problem +- Steps to reproduce (if possible) +- Expected vs actual behavior +- Environment details (browser, OS, version, framework, etc.) + +If you are unsure whether something is a bug, opening an issue is still fine — maintainers will help triage it. + +--- + +## Bug Triage + +Bug triage is the process of classifying and prioritizing reported bugs. + +### Responsibility + +- **Maintainers** are responsible for technical triage and classification +- **Product** may facilitate triage sessions, provide user-impact context, and help with communication +- **Contributors** may assist by reproducing issues or providing additional context + +--- + +### Classification + +Maintainers classify bugs based on technical severity. + +Severity reflects technical correctness and safety impact, not business priority or operational uptime. + +Severity levels: + +- **P0 – Critical**: *Unsafe or invalid to use as-is.* Crashes, data loss, security issues, or violations of documented invariants. Users cannot safely rely on the library. +- **P1 – High**: *Safe but seriously impaired.* Core functionality is broken or severely degraded. The library can still be used with limitations or workarounds. +- **P2 – Medium**: *Correct but inconvenient.* Partial breakage or confusing behavior with reasonable workarounds available. +- **P3 – Low**: *Annoying but non-blocking.* Minor issues or cosmetic bugs that do not affect correctness or core functionality. + +--- + +## Bug Lifecycle + +Bugs typically move through the following stages. Not all bugs go through every stage, and the process may vary depending on severity and complexity. + +1. **Reported** + + A bug is reported as a GitHub Issue by a user or contributor. + +2. **Triaged** + + Maintainers review the issue to confirm it is a bug, request additional information if needed, and classify severity. + +3. **Investigated** + + The issue is analyzed further. This may include reproducing the bug, identifying root causes, and discussing possible fixes or trade-offs. + +4. **Resolved** + + A fix is implemented and reviewed via a pull request, or a decision is made not to change behavior (for example, if the behavior is working as intended). + +5. **Closed** + + The issue is closed once resolved, deemed invalid, or no longer actionable. Closure should include a brief explanation whenever possible. + + +High-severity bugs (P0/P1) may skip stages or be addressed immediately. + +--- + +## Fixing Bugs + +- Bugs are fixed through the normal pull request process +- Anyone may submit a fix +- Maintainers review and approve fixes + +High-severity bugs may be addressed immediately, regardless of roadmap priorities. + +--- + +## Prioritization + +While maintainers determine technical severity, Product may: + +- Help prioritize bugs relative to other work +- Balance bug fixing with feature development +- Communicate expectations to users and stakeholders + +Bug prioritization does not override maintainer judgment on severity or correctness. + +--- + +## When a Bug Becomes an RFC + +If fixing a bug: + +- Requires changing core behavior +- Introduces breaking changes +- Sets new long-term precedent + +Then the fix may require an RFC. + +See [RFC_PROCESS.md](/RFC_PROCESS.md) and [How Work Flows](/HOW_WORK_FLOWS.md) for guidance. + +--- + +## Stale or Invalid Bugs + +Issues may be closed if: + +- The issue cannot be reproduced +- Required information is missing and no response is received +- The behavior is working as intended + + +> Closure should include a brief explanation. + + +--- + +## Guiding Principles + +- Bugs are treated seriously and respectfully +- Technical correctness comes before speed +- Transparency is preferred over silence +- When in doubt, discuss openly \ No newline at end of file diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000000..08b4ac51eb --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,47 @@ +# Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment include: + +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +- The use of sexualized language or imagery and unwelcome sexual attention or advances +- Trolling, insulting/derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others’ private information, such as a physical or electronic address, without explicit permission +- Other conduct which could reasonably be considered inappropriate in a professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies within all project spaces, and it also applies when an individual is representing the project or its community in public spaces. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [team@blocknotejs.org](mailto:team@blocknotejs.org). + +All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project’s leadership. + +## Attribution + +This Code of Conduct is adapted from the **Contributor Covenant**, version 1.4, available at: https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +For answers to common questions about this code of conduct, see: https://www.contributor-covenant.org/faq \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8fe42686f0..3ccd51d3a5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,85 @@ # Contributing -Directory structure: +Thank you for your interest in contributing to BlockNote. This project welcomes contributions from the community. This document explains how to participate, how decisions are made, and how to work with the codebase. + +--- + +## Ways to Contribute + +There are many ways to contribute to BlockNote: + +- Sharing ideas, feedback, or use cases +- Reporting bugs +- Improving documentation or examples + +- Proposing new features or changes +- Submitting code contributions + +You do NOT need to start with code to contribute. + +> Open-ended ideas, early exploration, and feedback are best shared via GitHub Discussions, while actionable work and implementation tasks are tracked as GitHub Issues. +> + +--- + +## Sharing Ideas and Feedback + +Ideas, suggestions, and early proposals are welcome and encouraged. + +- Start with a GitHub Issue or Discussion +- Focus on the problem or need, not just a solution +- Keep it lightweight — early feedback does not require an RFC + +See [How Work Flows](/HOW_WORK_FLOWS.md) for an overview of how ideas move through the project. + +--- + +## Proposing Significant Changes (RFCs) + +Some changes require an RFC (Request for Comments) before they can be accepted. + +An RFC is required when a change: + +- Affects core behavior or public APIs +- Introduces new core concepts +- Sets long-term technical precedent +- Has broad impact across users or integrations + +Anyone may propose an RFC. + +RFCs are intentionally higher-effort and are required only when a change is ready for formal consideration. + +See [RFC_PROCESS.md](/RFC_PROCESS.md) and [RFC_TEMPLATE.md](/.github/RFC_TEMPLATE.md) for details. + +--- + +## Code Contributions + +### Small Changes + +For small, low-risk changes (bug fixes, documentation, minor improvements): + +- Open a pull request directly +- Keep changes focused and scoped +- Include tests where appropriate + +Maintainers will review and provide feedback. + +--- + +### Larger Changes + +For larger or higher-impact changes: + +- Confirm whether an RFC is required +- Ensure the change aligns with an accepted RFC, if applicable +- Coordinate early with maintainers + +Pull requests that introduce significant changes without prior discussion may be redirected or closed. + +--- + +## Directory structure: ``` BlockNote @@ -19,7 +98,9 @@ BlockNote An introduction into the BlockNote Prosemirror schema can be found in [packages/core/src/pm-nodes/README.md](https://github.com/TypeCellOS/BlockNote/blob/main/packages/core/src/pm-nodes/README.md). -## Running +--- + +## Running the project To run the project, open the command line in the project's root directory and enter the following commands: @@ -31,11 +112,15 @@ pnpm install pnpm start ``` +--- + ## Adding packages - Add the dependency to the relevant `package.json` file (packages/xxx/package.json) - Double check `pnpm-lock.yaml` to make sure only the relevant packages have been affected +--- + ## Packages | Package | Size | Version | @@ -47,6 +132,8 @@ pnpm start | [@blocknote/shadcn](https://github.com/TypeCellOS/BlockNote/tree/main/packages/shadcn) | | | | [@blocknote/server-util](https://github.com/TypeCellOS/BlockNote/tree/main/packages/server-util) | | | +--- + ## Releasing This diagram illustrates the release workflow for the BlockNote monorepo. diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 0000000000..c610a8e281 --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,147 @@ +# Governance + +## 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. + +Governance is intentionally documented early to support trust with contributors, enterprises, and public-sector users. + +--- + +## Core Project Roles + +The project uses a simple three-role structure for project governance and technical authority. These roles define who makes technical decisions and how the project is stewarded over time. Individuals may hold multiple roles, but the authority exercised depends on the role relevant to the decision at hand. + +The project uses this structure designed to match its current size while supporting future growth. Individuals may hold multiple roles, but the authority exercised depends on the role relevant to the decision at hand. + +### Technical Steering Committee (TSC) + +> TSC members may also serve as maintainers. When doing so, they exercise only the authority of the role relevant to the decision at hand. + +The Technical Steering Committee (TSC) is responsible for the long-term technical direction and health of the project. + +The TSC operates independently of Product Management. Product may facilitate processes and provide input, but does not exercise technical decision-making authority or override TSC decisions. + +**Responsibilities**: + +- Approving or rejecting significant technical changes (via the [RFC process](/RFC_PROCESS.md)) +- Setting and maintaining long-term architectural direction +- Sanity-checking alignment with the project mission to prevent long-term drift +- Acting as stewards of the project’s technical integrity and sustainability + +**Privileges**: + +- Ability to curate and prioritize problem statements +- 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. + +Product management may also act as Product Owner (PO) for execution. When acting as PO, product management operates strictly within accepted RFC scope and does not override technical or governance decisions. + +--- + +### Contributors + +Contributors are individuals who participate in the project by contributing code, documentation, issues, or discussions. + +**Responsibilities**: + +- Following project guidelines and the Code of Conduct +- Engaging constructively with maintainers and other contributors + +**Privileges**: + +- Open participation in discussions, issues, and pull requests +- Ability to propose changes, ideas, and RFCs + +Contributors do not have merge rights or decision-making authority but are encouraged to grow into maintainer roles over time. + +--- + +## Supporting & Operational Roles + +Supporting and operational roles enable the project to function sustainably and transparently but do not exercise technical or governance authority over the project. + +### Steward + +The Steward is responsible for the legal, organizational, and operational continuity of the project. + +**Responsibilities**: + +- Holding and managing project assets (such as the GitHub organization, trademarks, domains, and release infrastructure) on behalf of the project +- Ensuring that documented governance processes are upheld and respected +- Providing long-term continuity and accountability for the project’s existence +- Acting as the primary legal and organizational point of contact for the project + +**Privileges**: + +- Administrative control over project assets and infrastructure +- Authority to act to protect the project’s continuity, security, or legal standing + +The Steward does not make technical decisions, does not participate in RFC acceptance, does not set technical direction, and does not override the authority of maintainers or the TSC. + +The project is currently stewarded by **XXX**, in their capacity as CEO of the stewarding company. + +--- + +### Product Management + +Product management gathers and synthesizes input from users, customers, and the community; maintains roadmap transparency; and facilitates the RFC process (for example by helping authors clarify motivation, scope, and impact). + +**Responsibilities**: + +- Aggregating and synthesizing input from users, customers, and contributors +- Framing problems and maintaining a transparent, indicative roadmap +- Facilitating the RFC process without exercising decision authority +- Preparing and facilitating operational processes such as regular bug triage + +**Privileges**: + +- Ability to curate and prioritize problem statements +- Ability to act as Product Owner (PO) for execution within accepted RFC scope +- Ability to establish and facilitate 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. + +Product management may also act as Product Owner (PO) for execution. When acting as PO, product management operates strictly within accepted RFC scope and does not override technical or governance decisions. + +--- + +## Decision-Making + +Decisions are handled through a risk-based escalation model: routine, low-impact work flows quickly, while high-impact or precedent-setting changes are explicitly reviewed. + +- Minor changes (bug fixes, documentation, small improvements) are handled through the normal pull request process. +- Significant changes require an RFC and TSC approval. +- The TSC aims to make decisions by consensus. If consensus cannot be reached, a simple majority vote may be used. + +Acceptance of an RFC indicates that a proposed technical approach is acceptable. Acceptance does not imply prioritization, scheduling, or a delivery commitment. + +**One-Sentence Policy**: + +> Product may facilitate processes and prioritize work, but technical correctness and severity decisions are owned by maintainers, and high-impact technical decisions are governed by the TSC. +> + +**Mental Model**: + +> Product runs the process. Maintainers run tcorrectness. The TSC guards long-term direction. +> + +--- + +## Advisory Input + +Enterprise and public-sector users may be invited to provide structured, non-binding feedback through advisory or consultation mechanisms. Advisory input does not grant decision-making authority and does not override governance processes. + +--- + +## Code of Conduct + +This project follows a Code of Conduct to ensure a welcoming and respectful community. All participants are expected to uphold these standards. + +--- + +## Governance Evolution + +As the contributor base grows, governance will evolve to include additional community maintainers and potentially expand the TSC. Any governance changes will be documented and discussed publicly. \ No newline at end of file diff --git a/HOW_WORK_FLOWS.md b/HOW_WORK_FLOWS.md new file mode 100644 index 0000000000..d3d612e4fd --- /dev/null +++ b/HOW_WORK_FLOWS.md @@ -0,0 +1,186 @@ +# How Work Flows + +This document describes how work moves through the project from an initial idea or user need to code being written, reviewed, and shipped. + +Its purpose is to provide a shared mental model for contributors, maintainers, Product, and the TSC, without prescribing heavy process. + +--- + +## The Mental Model (Overview) + +``` +Idea / Need + ↓ +Triage (what kind of thing is this?) + ↓ +Outcome + ├─ Bug → Bug process + ├─ Docs / Enablement → Docs or example PR + ├─ Small feature → Feature issue + └─ Significant change → RFC + ↓ + Accepted RFC (design allowed) + ↓ + Product translates into delivery work + ↓ + Engineering implements + ↓ + Maintainers review & merge + +``` + +This pipeline is risk-based: the higher the impact or precedent, the more explicit the decision-making. + +--- + +## Step 1: Idea or Need + +Ideas and needs can originate from many places: + +- Community contributors +- Enterprise or public-sector users +- Maintainers +- Product observations + +At this stage, ideas should be expressed as problems or needs, not solutions. Ideas may be shared informally to gather early feedback. Writing an RFC is not required at this stage. + +--- + +## Step 2: Triage + +The goal of triage is to decide what kind of work this is, not whether it will be done. + +Typical questions: + +- Is this a bug or broken behavior? +- Is this already possible and just poorly documented? +- Is this a small, local change? +- Does this affect core behavior, APIs, or long-term direction? + +Triage is usually facilitated by Product, with technical input from maintainers when needed. + +--- + +## Step 3: Outcome Paths + +### Does this need an RFC? + +Before choosing an outcome path, ask the following questions: + +- Does this change affect core behavior or public APIs? +- Does this introduce a new core concept or abstraction? +- Does this set a long-term technical precedent? +- Does this have broad impact across users, integrations, or deployments? + +If **YES** to any of the above → an RFC is required. + +If **NO** → proceed via the appropriate non-RFC path (bug, docs, or small feature). + +This decision is intentionally conservative: when in doubt, proposing an RFC is preferred over bypassing the process. + +--- + +### Bugs + +- Owned and triaged by maintainers +- Classified by technical severity (P0–P3) +- Fixed via the normal pull request process + +Product may help provide user impact context and communicate status, but does not decide technical severity. + +--- + +### Docs & Enablement + +If the need can be addressed through documentation, examples, or guidance: + +- A documentation or example pull request is created +- No RFC is required + +--- + +### Small Features + +If the change is: + +- Local in scope +- Low-risk +- Does not introduce new core concepts or public APIs + +Then: + +- A feature issue is created +- Product prioritizes the problem +- Engineering proposes and implements a solution +- Maintainers review and merge + +--- + +### Significant Changes (RFC) + +If the change: + +- Affects core behavior or public APIs +- Introduces new core concepts +- Sets long-term precedent +- Has broad user impact + +Then an RFC is required. + +RFCs are discussed openly and decided by the TSC. An RFC may be **accepted**, **rejected**, or **returned for revision**. + +Acceptance indicates that the proposed approach is technically acceptable. Rejection indicates that the approach should not proceed in its current form. + +Acceptance of an RFC does not imply prioritization, scheduling, or delivery commitment. + +--- + +## Step 4: RFC Decision Outcome + +If an RFC is: + +- **Accepted**: the design is allowed to move forward +- **Rejected**: the change does not proceed in its current form +- **Returned for revision**: the author may iterate and resubmit + +Detailed mechanics of RFC discussion and decision-making are documented separately in [RFC_PROCESS.md](/RFC_PROCESS.md). + +--- + +## Step 5: From Decision to Work + +Once a path is chosen: + +- **Accepted RFCs** are translated by Product into features or epics +- **Feature issues** are broken down by engineering into executable work +- Product schedules work based on capacity and priorities + +Engineering owns implementation details. Product owns sequencing and communication. + +--- + +## Step 5: Code, Review, and Shipping + +- Code is implemented via pull requests +- Maintainers review for correctness, quality, and alignment +- High-risk or precedent-setting changes follow the RFC decisions +- Approved changes are merged and released + +--- + +## Guiding Principles + +- Not all ideas need RFCs +- Not all accepted ideas are immediately implemented +- Authority escalates with impact +- Process exists to reduce confusion, not to slow work + +--- + +## Relationship to Other Documents + +- [GOVERNANCE.md](/GOVERNANCE.md) defines **who decides** +- [HOW_WORK_FLOWS.md](/HOW_WORK_FLOWS.md) defines **how work flows** +- [RFC_PROCESS.md](/RFC_PROCESS.md) (separate document) defines **how significant decisions are made** + +This document intentionally stays high-level and may evolve as the project grows. \ No newline at end of file diff --git a/MEMBERS.md b/MEMBERS.md new file mode 100644 index 0000000000..8129b8fdbf --- /dev/null +++ b/MEMBERS.md @@ -0,0 +1,34 @@ +# Project Members + +## Purpose + +This document lists individuals who hold formal roles within BlockNote (for example TSC members, maintainers, or other recognized roles). + +The purpose of this list is transparency, not hierarchy. + +## Listing Principles + +- Members are listed alphabetically, based on the first word of the name as written. +- Members are free to choose how they are listed (e.g. full name, preferred name, handle, or organization), as long as the chosen format is consistent for that individual. + +## Members + +### Steward + +- Yousef El-Dardiry [@YousefED](https://github.com/YousefED) + +### Technical Steering Committee (TSC) + +- Nick Perez [@nperez0111](https://github.com/nperez0111) +- Yousef El-Dardiry [@YousefED](https://github.com/YousefED) +- (*Vacant, reserved for a future community maintainer)* + +### Maintainers + +- Matthew Lipski [@matthewlipski](https://github.com/matthewlipski/) +- Nick Perez [@nperez0111](https://github.com/nperez0111) +- Yousef El-Dardiry [@YousefED](https://github.com/YousefED) + +### Product Management + +- Wouter Vroege [@woutervroege](https://github.com/woutervroege/) \ No newline at end of file diff --git a/MISSION.md b/MISSION.md new file mode 100644 index 0000000000..c1ae465431 --- /dev/null +++ b/MISSION.md @@ -0,0 +1,27 @@ +# Mission + +BlockNote’s mission is to make it easy for developers to embed a modern, high-quality rich-text editing experience into their applications, while maximizing developer control. + +--- + +## Vision + +BlockNote aims to be the most trusted open foundation for rich-text editing in modern web applications. + +BlockNote enables editing experiences comparable to industry leaders, while remaining fully open, developer-controlled, and adaptable to a wide range of use cases. We aim for long-term maintainability, extensibility, and collaboration across a diverse ecosystem of applications. + +--- + +## How the Mission Guides Decisions + +The mission is not only descriptive; it is intended to guide decision‑making across the project. + +When evaluating ideas, RFCs, prioritization decisions, or technical changes, maintainers, Product, and the Technical Steering Committee (TSC) are expected to consider the following questions: + +- Does this improve the developer experience of integrating and using BlockNote? +- Does this contribute to a high-quality and accessible end-user editing experience when integrated into an application? +- Does this preserve or enhance the extensible, modular, and developer-controlled nature of the library? +- Does this align with a modern, block-based editing model? +- Does this preserve or enhance collaborative editing experiences? + +Proposals that clearly align with the mission are more likely to be accepted. Proposals that conflict with the mission may be declined or redirected, even if they are technically feasible. \ No newline at end of file diff --git a/RFC_PROCESS.md b/RFC_PROCESS.md new file mode 100644 index 0000000000..224ef19756 --- /dev/null +++ b/RFC_PROCESS.md @@ -0,0 +1,91 @@ +# Request for Comments (RFC) Process + +This document describes how significant technical changes are proposed, discussed, and decided using the RFC (Request for Comments) process. + +RFCs are intentionally higher-effort than informal ideas. They are required only when a change is ready for formal consideration and decision. + +Early ideas, explorations, and feedback should be shared informally before committing to an RFC. + +--- + +## **What Requires an RFC** + +An RFC is required for changes that: + +- Affect core behavior or public APIs +- Introduce new core concepts or abstractions +- Set long-term technical precedent +- Have broad impact across users, integrations, or deployments + +Not all ideas require an RFC. See **How Work Flows** for guidance on early idea sharing and triage. + +--- + +## **Who Can Propose an RFC** + +Anyone may propose an RFC, including: + +- Community contributors +- Maintainers +- Product +- Members of the TSC + +--- + +## **RFC Champion** + +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: + +- Drive the RFC forward +- Incorporate feedback +- Clarify trade-offs and open questions + +Champions do not have decision-making authority. Maintainers and the TSC are expected to support first-time champions. + +--- + +## **RFC Lifecycle** + +### **Draft & Discussion** + +- RFCs are created using the RFC template +- Discussion happens openly +- RFCs may evolve during discussion and early prototyping + +--- + +### **Decision** + +The Technical Steering Committee (TSC) is responsible for RFC decisions. + +An RFC may be: + +- **Accepted:** the proposed approach is technically acceptable +- **Rejected:** the approach should not proceed in its current form +- **Revision Requested:** further work or clarification is needed + +Decisions are recorded publicly with a clear rationale. + +--- + +## **From Accepted RFC to Implementation** + +Once an RFC is accepted, responsibility transitions from governance to execution. + +- The **TSC** confirms that the proposed approach is technically acceptable and records the decision. +- **Product** determines whether, when, and how the accepted RFC is translated into delivery work, based on priorities and available capacity. +- **Engineering** owns implementation details within the scope of the accepted RFC. +- **Maintainers** review implementation for correctness, quality, and alignment with the accepted decision. + +Acceptance of an RFC does **not** imply prioritization, scheduling, or a delivery commitment. + +--- + +## **Guiding Principles** + +- RFCs exist to clarify decisions, not to block progress +- Escalate decision-making with impact +- Keep RFCs lightweight and focused +- Prefer early discussion over late surprises \ No newline at end of file diff --git a/TEAM_OPERATIONS.md b/TEAM_OPERATIONS.md new file mode 100644 index 0000000000..ac306b480e --- /dev/null +++ b/TEAM_OPERATIONS.md @@ -0,0 +1,214 @@ +# Team Operations + +This document describes how the core team collaborates day to day to plan, prioritize, and deliver work. It complements higher-level documents such as [How Work Flows](/HOW_WORK_FLOWS.md), [GOVERNANCE](/GOVERNANCE.md), and the [RFC process](/RFC_PROCESS.md) by focusing on practical execution rather than decision authority. + +The goal is to provide clarity without bureaucracy, and to support a small, senior team working on an open-source library used by a diverse community. + +--- + +## Operating Model + +The project uses a **Kanban-style, continuous flow** model rather than time-boxed sprints. + +This approach is chosen because: + +- Work arrives unpredictably (bugs, community input, enterprise needs) +- The team is small and context switching is common +- The project values flexibility and transparency over fixed commitments + +--- + +## Work Streams + +All work falls into one of three streams. These streams share the same board and flow, and are distinguished by labels or swimlanes. + +### 1. Maintenance + +Includes: + +- Bug fixes and regressions +- Stability, performance, and infrastructure work +- Small refactors and technical hygiene + +Maintenance work is governed by the bug triage process and maintainer judgment. + +--- + +### 2. Discovery + +Discovery work focuses on reducing uncertainty before committing to delivery. It may or may not lead to implementation. + +Includes: + +- Early idea exploration +- Exploration to reduce technical, UX, or API uncertainty (for example research, prototypes, or throwaway code) +- RFC preparation and refinement + +Discovery work is typically time-boxed and produces learning or clarity rather than shipped features. + +--- + +### 3. Delivery + +Includes: + +- Implementation of accepted RFCs +- Small changes that do not require an RFC + +Delivery work turns approved decisions into shipped code. Acceptance of an RFC enables delivery, but does not guarantee prioritization. + +--- + +## The Board + +The team uses a single shared board to track work. + +### Columns + +- **Inbox** – Untriaged ideas, bugs, and requests. No commitment. +- **Ready** – Work that is understood and allowed to be started. +- **In Progress** – Actively worked on items. +- **Review** – Work awaiting review or feedback. +- **Done** – Completed and merged work. + +The board is an operational tool, not a roadmap. + +--- + +## Ready Criteria + +An item may move to **Ready** when: + +- The scope and intent are clear +- It is appropriate to work on + - Bugs are classified by severity + - Features either have an accepted RFC or are explicitly deemed not to require one + +The Ready column represents permission to start work, not a priority order. + +--- + +## Prioritization of Ready Items + +Prioritization determines what the team focuses on next from the Ready column. It does not affect what is allowed to be worked on. + +### How Prioritization Works + +- Prioritization happens collaboratively, typically during the weekly sync +- Product proposes a focus based on user needs, enterprise context, and strategic considerations +- Engineering provides input on technical risk, sequencing, and capacity + +The outcome is a shared agreement on near-term focus, not a binding commitment or delivery promise. + +### Roles and Responsibilities + +- **Product** facilitates prioritization by surfacing context, trade-offs, and suggested focus areas +- **Maintainers** retain authority over technical feasibility and sequencing +- **No single role owns prioritization**; decisions are made through discussion and consensus + +High-severity maintenance work (for example P0 or P1 bugs) may be prioritized immediately regardless of other Ready items. + +--- + +## Roles in Day-to-Day Operations + +### Maintainers + +- Own technical decisions +- Triage and classify bugs +- Review and merge pull requests +- Decide how work is implemented + +--- + +### Product Management / Product Owner + +Product management supports execution by: + +- Curating the Inbox +- Facilitating bug triage +- Helping prepare items for Ready +- Translating accepted RFCs into epics or work items +- Proposing focus and sequencing +- Communicating status externally + +Product does not assign work or override maintainer or TSC authority. When acting as Product Owner, Product operates strictly within accepted scope. + +--- + +### Technical Steering Committee (TSC) + +The TSC is not involved in daily operations. Its role is to: + +- Accept or reject RFCs +- Ensure alignment with the project mission +- Guard long-term technical direction + +--- + +## Cadence + +### Daily + +The team uses a lightweight, daily check-in to share: + +- What was worked on +- What is planned next +- What is blocking them + +--- + +### Weekly Sync + +A weekly sync (30–45 minutes) is held between engineering and product. + +Typical agenda: + +1. Review completed work +2. Review items in progress +3. Review Ready items +4. Time-boxed triage of Inbox items + +The outcome is shared alignment on near-term focus, not delivery commitments. + +--- + +### Reflections and Continuous Improvement + +The team periodically reflects on how it works together and may adjust practices as needed. + +Reflections are lightweight and focused on identifying friction, validating what works well, and experimenting with small improvements. They are not performance evaluations and do not produce formal action plans. + +--- + +## Decision Recording + +Synchronous discussions (for example chat or calls) are encouraged for speed and alignment. However, decisions that affect others or have lasting impact should be recorded in GitHub. + +As a general rule: + +- Decisions may be made synchronously +- Outcomes should be summarized asynchronously in GitHub issues, pull requests, or RFCs + +This ensures transparency, long-term traceability, and shared understanding across the project. + +--- + +## Guiding Principles + +- Keep work visible +- Limit work in progress +- Prefer flow over fixed plans +- Optimize for trust and clarity +- Avoid process that does not clearly add value + +--- + +## Relationship to Other Documents + +- [How Work Flows](/HOW_WORK_FLOWS.md) describes the conceptual lifecycle from ideas to code +- [RFC Process](/RFC_PROCESS.md) governs significant technical decisions +- [GOVERNANCE](/GOVERNANCE.md) defines authority and decision rights +- [BUGS](/BUGS.md) defines bug reporting and triage + +This document focuses exclusively on how the core team executes work within those constraints. \ No newline at end of file