From 5a9ee19eb82dc648a3aa356621e8ff963b289ead Mon Sep 17 00:00:00 2001 From: Dave Allie Date: Thu, 5 Feb 2026 22:38:42 +1100 Subject: [PATCH] docs: Add small SCOPE.md and GOVERNANCE.md documents (#640) ## Summary * Additional documentation for CrossPoint in the way of a SCOPE.md and GOVERNANCE.md document. * These are intentionally pretty lightweight for now --- ### AI Usage While CrossPoint doesn't have restrictions on AI tools in contributing, please be transparent about their usage as it helps set the right context for reviewers. Did you use AI tools to help write this code? Partially --- GOVERNANCE.md | 38 ++++++++++++++++++++++++++++++++++++++ README.md | 11 ++++++++--- SCOPE.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 94 insertions(+), 3 deletions(-) create mode 100644 GOVERNANCE.md create mode 100644 SCOPE.md diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 00000000..4c14bc54 --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,38 @@ +# 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. +- If you want to report a bug, check for duplicates and create an + [Issue](https://github.com/crosspoint-reader/crosspoint-reader/issues). +- 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/README.md b/README.md index 151c6293..464531d9 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 @@ -152,9 +154,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 diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 00000000..2f61d512 --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,48 @@ +# 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 + +*These are features that directly improve the primary purpose of the device.* + +* **User Experience:** E.g. User-friendly interfaces, and interactions, both inside the reader and navigating the + firmware. This includes things like button mapping, book loading, and book navigation like bookmarks. +* **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. +* **Language Support:** E.g. Support for multiple languages both in the reader and in the interfaces. + +### Out-of-Scope + +*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. +* **Complex Reader Features:** No highlighting, notes, or dictionary lookup. These features are better suited for + devices with better input capabilities and more powerful chips. + +## 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!