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
This commit is contained in:
Dave Allie 2026-02-05 22:38:42 +11:00 committed by GitHub
parent c49a819939
commit 5a9ee19eb8
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 94 additions and 3 deletions

38
GOVERNANCE.md Normal file
View File

@ -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
its 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 projects technical direction to
ensure stability on the ESP32-C3s 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.

View File

@ -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

48
SCOPE.md Normal file
View File

@ -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!