A fork of https://github.com/crosspoint-reader/crosspoint-reader
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
authored by
Dave Allie
and committed by
GitHub
5a9ee19e
c49a8199
+94
-3
+38
GOVERNANCE.md
+38
GOVERNANCE.md
···
1
+
# Project Governance & Community Principles
2
+
3
+
CrossPoint Reader is a community-driven, open-source project. Our goal is to provide a high-quality, open-source
4
+
firmware alternative for the Xteink X4 hardware. To keep this project productive and welcoming as we grow, we ask all
5
+
contributors to follow these principles.
6
+
7
+
### 1. The "Human First" Rule
8
+
Technical discussions can get heated, but they should never be personal.
9
+
- **Assume good intent:** We are all volunteers working on this in our free time. If a comment seems abrasive, assume
10
+
it’s a language barrier or a misunderstanding before taking offense.
11
+
- **Focus on the code, not the person:** Critique the implementation, the performance, or the UX. Never the intelligence
12
+
or character of the contributor.
13
+
- **Inflammatory language:** Personal attacks, trolling, or exclusionary language (based on race, gender, background,
14
+
etc.) are not welcome here and will be moderated.
15
+
16
+
### 2. A "Do-ocracy" with Guidance
17
+
CrossPoint thrives because people step up to build what they want to see.
18
+
- If you want a feature, the best way to get it is to start an
19
+
[Idea Discussion](https://github.com/crosspoint-reader/crosspoint-reader/discussions/categories/ideas) or open a PR.
20
+
- If you want to report a bug, check for duplicates and create an
21
+
[Issue](https://github.com/crosspoint-reader/crosspoint-reader/issues).
22
+
- While we encourage experimentation, the maintainers reserve the right to guide the project’s technical direction to
23
+
ensure stability on the ESP32-C3’s constrained hardware.
24
+
- For more guidance on the scope of the project, see the [SCOPE.md](SCOPE.md) document.
25
+
26
+
### 3. Transparent Communication
27
+
To keep the project healthy, we keep our "work" in the open.
28
+
- **Public by Default:** All technical decisions and project management discussions happen in GitHub Issues, Pull
29
+
Requests, or the public Discussions tab.
30
+
- **Clarity in Writing:** Because we have a global community with different levels of English proficiency, please be as
31
+
explicit and clear as possible in your PR descriptions and bug reports.
32
+
33
+
### 4. Moderation & Safety
34
+
The maintainers are responsible for keeping the community a safe place to contribute.
35
+
- We reserve the right to hide comments, lock threads, or block users who repeatedly violate these principles or engage
36
+
in harassment.
37
+
- **Reporting:** If you feel you are being harassed or see behavior that is damaging the community, please reach out
38
+
privately to @daveallie.
+8
-3
README.md
+8
-3
README.md
···
45
45
46
46
See [the user guide](./USER_GUIDE.md) for instructions on operating CrossPoint.
47
47
48
+
For more details about the scope of the project, see the [SCOPE.md](SCOPE.md) document.
49
+
48
50
## Installing
49
51
50
52
### Web (latest firmware)
···
58
60
### Web (specific firmware version)
59
61
60
62
1. Connect your Xteink X4 to your computer via USB-C
61
-
2. Download the `firmware.bin` file from the release of your choice via the [releases page](https://github.com/daveallie/crosspoint-reader/releases)
63
+
2. Download the `firmware.bin` file from the release of your choice via the [releases page](https://github.com/crosspoint-reader/crosspoint-reader/releases)
62
64
3. Go to https://xteink.dve.al/ and flash the firmware file using the "OTA fast flash controls" section
63
65
64
66
To revert back to the official firmware, you can flash the latest official firmware from https://xteink.dve.al/, or swap
···
82
84
CrossPoint uses PlatformIO for building and flashing the firmware. To get started, clone the repository:
83
85
84
86
```
85
-
git clone --recursive https://github.com/daveallie/crosspoint-reader
87
+
git clone --recursive https://github.com/crosspoint-reader/crosspoint-reader
86
88
87
89
# Or, if you've already cloned without --recursive:
88
90
git submodule update --init --recursive
···
152
154
153
155
Contributions are very welcome!
154
156
155
-
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).
157
+
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).
156
158
If there's something there you'd like to work on, leave a comment so that we can avoid duplicated effort.
159
+
160
+
Everyone here is a volunteer, so please be respectful and patient. For more details on our goverance and community
161
+
principles, please see [GOVERNANCE.md](GOVERNANCE.md).
157
162
158
163
### To submit a contribution:
159
164
+48
SCOPE.md
+48
SCOPE.md
···
1
+
# Project Vision & Scope: CrossPoint Reader
2
+
3
+
The goal of CrossPoint Reader is to create an efficient, open-source reading experience for the Xteink X4. We believe a
4
+
dedicated e-reader should do one thing exceptionally well: **facilitate focused reading.**
5
+
6
+
## 1. Core Mission
7
+
8
+
To provide a lightweight, high-performance firmware that maximizes the potential of the X4, prioritizing legibility and
9
+
usability over "swiss-army-knife" functionality.
10
+
11
+
## 2. Scope
12
+
13
+
### In-Scope
14
+
15
+
*These are features that directly improve the primary purpose of the device.*
16
+
17
+
* **User Experience:** E.g. User-friendly interfaces, and interactions, both inside the reader and navigating the
18
+
firmware. This includes things like button mapping, book loading, and book navigation like bookmarks.
19
+
* **Document Rendering:** E.g. Support for rendering documents (primarily EPUB) and improvements to the rendering
20
+
engine.
21
+
* **Format Optimization:** E.g. Efficiently parsing EPUB (CSS/Images) and other documents within the device's
22
+
capabilities.
23
+
* **Typography & Legibility:** E.g. Custom font support, hyphenation engines, and adjustable line spacing.
24
+
* **E-Ink Driver Refinement:** E.g. Reducing full-screen flashes (ghosting management) and improving general rendering.
25
+
* **Library Management:** E.g. Simple, intuitive ways to organize and navigate a collection of books.
26
+
* **Local Transfer:** E.g. Simple, "pull" based book loading via a basic web-server or public and widely-used standards.
27
+
* **Language Support:** E.g. Support for multiple languages both in the reader and in the interfaces.
28
+
29
+
### Out-of-Scope
30
+
31
+
*These items are rejected because they compromise the device's stability or mission.*
32
+
33
+
* **Interactive Apps:** No Notepads, Calculators, or Games. This is a reader, not a PDA.
34
+
* **Active Connectivity:** No RSS readers, News aggregators, or Web browsers. Background Wi-Fi tasks drain the battery
35
+
and complicate the single-core CPU's execution.
36
+
* **Media Playback:** No Audio players or Audio-books.
37
+
* **Complex Reader Features:** No highlighting, notes, or dictionary lookup. These features are better suited for
38
+
devices with better input capabilities and more powerful chips.
39
+
40
+
## 3. Idea Evaluation
41
+
42
+
While I appreciate the desire to add new and exciting features to CrossPoint Reader, CrossPoint Reader is designed to be
43
+
a lightweight, reliable, and performant e-reader. Things which distract or compromise the device's core mission will not
44
+
be accepted. As a guiding question, consider if your idea improve the "core reading experience" for the average user,
45
+
and, critically, not distract from that reading experience.
46
+
47
+
> **Note to Contributors:** If you are unsure if your idea fits the scope, please open a **Discussion** before you start
48
+
> coding!