From 29404399883bcd7db0e7a712a8333a226fc99623 Mon Sep 17 00:00:00 2001 From: Dave Allie Date: Sun, 1 Feb 2026 20:52:05 +1100 Subject: [PATCH 1/2] docs: Add small SCOPE.md and GOVERNANCE.md documents --- GOVERNANCE.md | 36 ++++++++++++++++++++++++++++++++++++ SCOPE.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 79 insertions(+) create mode 100644 GOVERNANCE.md create mode 100644 SCOPE.md diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 00000000..1a300451 --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,36 @@ +# Project Governance & Community Principles + +CrossPoint Reader is a community-driven, open-source project. Our goal is to provide a high-quality, open-source +firmware alternative for the Xteink X4 hardware. To keep this project productive and welcoming as we grow, we ask all +contributors to follow these principles. + +### 1. The "Human First" Rule +Technical discussions can get heated, but they should never be personal. +- **Assume good intent:** We are all volunteers working on this in our free time. If a comment seems abrasive, assume + it’s a language barrier or a misunderstanding before taking offense. +- **Focus on the code, not the person:** Critique the implementation, the performance, or the UX. Never the intelligence + or character of the contributor. +- **Inflammatory language:** Personal attacks, trolling, or exclusionary language (based on race, gender, background, + etc.) are not welcome here and will be moderated. + +### 2. A "Do-ocracy" with Guidance +CrossPoint thrives because people step up to build what they want to see. +- If you want a feature, the best way to get it is to start an + [Idea Discussion](https://github.com/crosspoint-reader/crosspoint-reader/discussions/categories/ideas) or open a PR. +- While we encourage experimentation, the maintainers reserve the right to guide the project’s technical direction to + ensure stability on the ESP32-C3’s constrained hardware. +- For more guidance on the scope of the project, see the [SCOPE.md](SCOPE.md) document. + +### 3. Transparent Communication +To keep the project healthy, we keep our "work" in the open. +- **Public by Default:** All technical decisions and project management discussions happen in GitHub Issues, Pull + Requests, or the public Discussions tab. +- **Clarity in Writing:** Because we have a global community with different levels of English proficiency, please be as + explicit and clear as possible in your PR descriptions and bug reports. + +### 4. Moderation & Safety +The maintainers are responsible for keeping the community a safe place to contribute. +- We reserve the right to hide comments, lock threads, or block users who repeatedly violate these principles or engage + in harassment. +- **Reporting:** If you feel you are being harassed or see behavior that is damaging the community, please reach out + privately to @daveallie. diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 00000000..bac53dae --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,43 @@ +# Project Vision & Scope: CrossPoint Reader + +The goal of CrossPoint Reader is to create an efficient, open-source reading experience for the Xteink X4. We believe a +dedicated e-reader should do one thing exceptionally well: **facilitate focused reading.** + +## 1. Core Mission + +To provide a lightweight, high-performance firmware that maximizes the potential of the X4, prioritizing legibility and +usability over "swiss-army-knife" functionality. + +## 2. Scope + +### In-Scope: The "Core Reading Experience" + +*These are features that directly improve the primary purpose of the device.* + +* **Document Rendering:** E.g. Support for rendering documents (primarily EPUB) and improvements to the rendering + engine. +* **Format Optimization:** E.g. Efficiently parsing EPUB (CSS/Images) and other documents within the device's + capabilities. +* **Typography & Legibility:** E.g. Custom font support, hyphenation engines, and adjustable line spacing. +* **E-Ink Driver Refinement:** E.g. Reducing full-screen flashes (ghosting management) and improving general rendering. +* **Library Management:** E.g. Simple, intuitive ways to organize and navigate a collection of books. +* **Local Transfer:** E.g. Simple, "pull" based book loading via a basic web-server or public and widely-used standards. + +### Out-of-Scope: The "Feature Creep" Guardrail + +*These items are rejected because they compromise the device's stability or mission.* + +* **Interactive Apps:** No Notepads, Calculators, or Games. This is a reader, not a PDA. +* **Active Connectivity:** No RSS readers, News aggregators, or Web browsers. Background Wi-Fi tasks drain the battery + and complicate the single-core CPU's execution. +* **Media Playback:** No Audio players or Audio-books + +## 3. Idea Evaluation + +While I appreciate the desire to add new and exciting features to CrossPoint Reader, CrossPoint Reader is designed to be +a lightweight, reliable, and performant e-reader. Things which distract or compromise the device's core mission will not +be accepted. As a guiding question, consider if your idea improve the "core reading experience" for the average user, +and, critically, not distract from that reading experience. + +> **Note to Contributors:** If you are unsure if your idea fits the scope, please open a **Discussion** before you start +> coding! From e08cf3ff02f636aa85826c6b8e8d102a351106fa Mon Sep 17 00:00:00 2001 From: Dave Allie Date: Sun, 1 Feb 2026 20:55:35 +1100 Subject: [PATCH 2/2] Update README.md --- README.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 633ae3b8..1f0e7101 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,8 @@ Multi-language support: Read EPUBs in various languages, including English, Span See [the user guide](./USER_GUIDE.md) for instructions on operating CrossPoint. +For more details about the scope of the project, see the [SCOPE.md](SCOPE.md) document. + ## Installing ### Web (latest firmware) @@ -58,7 +60,7 @@ back to the other partition using the "Swap boot partition" button here https:// ### Web (specific firmware version) 1. Connect your Xteink X4 to your computer via USB-C -2. Download the `firmware.bin` file from the release of your choice via the [releases page](https://github.com/daveallie/crosspoint-reader/releases) +2. Download the `firmware.bin` file from the release of your choice via the [releases page](https://github.com/crosspoint-reader/crosspoint-reader/releases) 3. Go to https://xteink.dve.al/ and flash the firmware file using the "OTA fast flash controls" section To revert back to the official firmware, you can flash the latest official firmware from https://xteink.dve.al/, or swap @@ -82,7 +84,7 @@ See [Development](#development) below. CrossPoint uses PlatformIO for building and flashing the firmware. To get started, clone the repository: ``` -git clone --recursive https://github.com/daveallie/crosspoint-reader +git clone --recursive https://github.com/crosspoint-reader/crosspoint-reader # Or, if you've already cloned without --recursive: git submodule update --init --recursive @@ -133,9 +135,12 @@ For more details on the internal file structures, see the [file formats document Contributions are very welcome! -If you're looking for a way to help out, take a look at the [ideas discussion board](https://github.com/daveallie/crosspoint-reader/discussions/categories/ideas). +If you're looking for a way to help out, take a look at the [ideas discussion board](https://github.com/crosspoint-reader/crosspoint-reader/discussions/categories/ideas). If there's something there you'd like to work on, leave a comment so that we can avoid duplicated effort. +Everyone here is a volunteer, so please be respectful and patient. For more details on our goverance and community +principles, please see [GOVERNANCE.md](GOVERNANCE.md). + ### To submit a contribution: 1. Fork the repo