forked from upstream-mirrors/quik
docs: standardize fork README and disclose AI-assisted development
Build and Release APK / Build APK (push) Successful in 4m3s
Build and Release APK / Build APK (push) Successful in 4m3s
This commit is contained in:
@@ -1,23 +1,52 @@
|
||||
# Quik Fork with Remotrix Matrix Bridge
|
||||
# QUIK — Remotrix Matrix bridge fork
|
||||
|
||||
> [!NOTE]
|
||||
> This project is a hard fork of the open-source **Quik** SMS messenger application. It has been modified to natively integrate **Remotrix**, a background service that bridges your SMS messages to a Matrix homeserver.
|
||||
An Android SMS messenger based on QUIK, with an integrated Remotrix service that bridges SMS messages to Matrix.
|
||||
|
||||
## Why this fork?
|
||||
**Upstream:** [octoshrimpy/quik](https://github.com/octoshrimpy/quik).
|
||||
**Fork repository:** [karol/quik](https://gitea.labus.uk/karol/quik).
|
||||
|
||||
[Fork purpose](#fork-purpose) · [Changes from upstream](#changes-from-upstream) · [Requirements](#requirements) · [Getting started](#getting-started) · [Configuration](#configuration) · [Usage](#usage) · [Development](#development) · [Upstream maintenance](#upstream-maintenance) · [Documentation](#documentation) · [Credits](#credits) · [License](#license)
|
||||
|
||||
## Fork purpose
|
||||
|
||||
The original Remotrix project was a standalone background bridge that required a separate, default SMS handler application. By deeply integrating Remotrix directly into Quik, we created a single, unified SMS application that offers a beautiful Material Design UI on the phone, while silently syncing all messages to your Matrix account (via Trixnity) in the background.
|
||||
|
||||
**Key enhancements in this fork:**
|
||||
* **Native Matrix Background Sync**: SMS messages sent or received on the phone are instantly bridged to your Matrix account.
|
||||
* **Two-way Communication**: Messages sent from Matrix are instantly forwarded as standard SMS messages from the phone.
|
||||
* **Coroutines Deadlock Fix**: Upgraded Room database dependencies to resolve fatal `SQLiteConnectionPool` deadlocks during the cryptographic key generation phases.
|
||||
* **Enhanced Visual Formatting**: Matrix messages now use intuitive prefixes (🟢 for outgoing, 🔴 for incoming) to clearly distinguish participants without requiring AppService double puppeting.
|
||||
* **Gitea Actions CI/CD**: Includes automated builds and automatic upstream fetching from the original Quik repository.
|
||||
## Changes from upstream
|
||||
|
||||
## Management Room
|
||||
- **Native Matrix Background Sync**: SMS messages sent or received on the phone are instantly bridged to your Matrix account.
|
||||
- **Two-way Communication**: Messages sent from Matrix are instantly forwarded as standard SMS messages from the phone.
|
||||
- **Coroutines Deadlock Fix**: Upgraded Room database dependencies to resolve fatal `SQLiteConnectionPool` deadlocks during the cryptographic key generation phases.
|
||||
- **Enhanced Visual Formatting**: Matrix messages now use intuitive prefixes (🟢 for outgoing, 🔴 for incoming) to clearly distinguish participants without requiring AppService double puppeting.
|
||||
- **Gitea Actions CI/CD**: Includes automated builds and automatic upstream fetching from the original Quik repository.
|
||||
|
||||
When you log into the application with your Matrix bot account (`@remotrix:yourserver.com`) and specify a Manager ID (`@you:yourserver.com`), the bot creates a dedicated **Management Room** and invites you.
|
||||
## Requirements
|
||||
|
||||
- An Android device with SMS support for sending and receiving messages.
|
||||
- A Matrix homeserver, bridge account, and Manager ID for Matrix integration.
|
||||
- JDK 17 and the Android SDK for local builds.
|
||||
- A persistent signing key for Release builds; Debug builds do not need release credentials.
|
||||
|
||||
## Getting started
|
||||
|
||||
Download APKs from [this fork's Gitea releases](https://gitea.labus.uk/karol/quik/releases). For local development, run:
|
||||
|
||||
```bash
|
||||
./gradlew assembleDebug
|
||||
```
|
||||
|
||||
Debug APKs are written to `presentation/build/outputs/apk/debug/`. Debug builds use a separate application ID. Upstream download links in `README.upstream.md` distribute QUIK without this fork's Matrix integration.
|
||||
|
||||
## Configuration
|
||||
|
||||
In QUIK settings, open the Matrix login dialog, sign in with the bridge account, and set your Manager ID. For release signing configuration, see [Development](#development).
|
||||
|
||||
## Usage
|
||||
|
||||
### Management room
|
||||
|
||||
When you log into the application with your Matrix bot account (`@remotrix:yourserver.com`) and specify a Manager ID (`@you:yourserver.com`), the bot creates a dedicated **Management Room** and invites you.
|
||||
From there, you can issue commands:
|
||||
|
||||
- `!new <phone_number>` - Opens a new Matrix room dedicated to chatting with that phone number.
|
||||
- `!close` - Deletes a chat room.
|
||||
- `!ping` - Checks bot latency.
|
||||
@@ -25,7 +54,7 @@ From there, you can issue commands:
|
||||
|
||||
Any non-command text sent in a dedicated phone number room will be sent as an SMS to that contact.
|
||||
|
||||
## Starting over with Matrix
|
||||
### Reset Matrix
|
||||
|
||||
In Quik settings, open the Matrix login dialog and select **Reset Matrix**.
|
||||
Confirm the reset, remove the old rooms on your Matrix server, then sign in again.
|
||||
@@ -33,7 +62,7 @@ The reset removes local Matrix accounts, room mappings, encryption stores and br
|
||||
SMS messages, Quik settings, the Manager ID and the backfill limit are preserved.
|
||||
New rooms use contact names from Android, and SMS history is copied again up to the configured limit.
|
||||
|
||||
## History import
|
||||
### History import
|
||||
|
||||
History import retries a failed message before advancing, with retry delays up to one minute.
|
||||
Synapse room-creation limits still apply. There is no fixed delay after each successful message.
|
||||
@@ -48,7 +77,9 @@ older versions did not retain per-message progress, so replaying that history co
|
||||
Checkpoint storage and the Matrix outbox use separate databases; an abrupt process/device failure
|
||||
between enqueueing a message and saving its checkpoint can still replay that last message.
|
||||
|
||||
## Persistent release signing
|
||||
## Development
|
||||
|
||||
### Persistent release signing
|
||||
|
||||
Release APKs require the permanent signing key. Missing signing configuration fails the build;
|
||||
release builds never fall back to a generated debug key. Pull requests build and test Debug
|
||||
@@ -77,117 +108,22 @@ The former builds 50 and 51 used different disposable debug certificates. The ne
|
||||
cannot update either installation in place; migrating once to the new certificate requires a
|
||||
reinstall. Subsequent Release updates keep the same signature.
|
||||
|
||||
## Building and Releasing (Fork CI/CD)
|
||||
### Builds and releases
|
||||
|
||||
The project uses Gitea Actions for CI/CD:
|
||||
- `build.yml`: Automatically builds the Debug and Release APKs (`assembleDebug`, `assembleRelease`) upon pushing to `master` or creating a tag. If a tag (e.g., `v1.0.0`) is pushed, a Gitea Release is created automatically.
|
||||
|
||||
- `build.yml`: Runs tests and builds Debug APKs for pull requests to `master`. Pushes to `master` and `v*` tags also build signed Release APKs and publish a Gitea release after verification.
|
||||
- `sync.yml`: Runs weekly to automatically fetch changes from the original `quik` upstream repository and merge them into our fork.
|
||||
|
||||
To build manually:
|
||||
|
||||
```bash
|
||||
./gradlew assembleDebug
|
||||
```
|
||||
|
||||
The APK will be available in `presentation/build/outputs/apk/debug/`.
|
||||
|
||||
---
|
||||
|
||||
# Original Quik Documentation Below:
|
||||
|
||||

|
||||
|
||||
# QUIK
|
||||
|
||||
[](https://github.com/octoshrimpy/quik/actions/workflows/manual-release.yml)
|
||||
<a href="https://hosted.weblate.org/engage/quik/"><img src="https://hosted.weblate.org/widget/quik/svg-badge.svg" alt="Translation status" /></a>
|
||||
[](https://deepwiki.com/octoshrimpy/quik)
|
||||
|
||||
QUIK is an open source replacement to the [stock messaging app](https://github.com/android/platform_packages_apps_mms) on Android. It is a continuation of [QKSMS](https://github.com/moezbhatti/qksms).
|
||||
|
||||
## Features
|
||||
|
||||
- Scheduled messages
|
||||
- Message backup
|
||||
- Speech-to-text and text-to-speech integrated within the app
|
||||
- Message blocking and archiving
|
||||
- Voice messages
|
||||
- Attachments of any type of file
|
||||
- Message sorting
|
||||
- Message pinning
|
||||
- Delayed sending
|
||||
- Quick reply from notifications
|
||||
- Swipe actions
|
||||
- Emoji reaction handling
|
||||
- and much, much more
|
||||
|
||||
## Download
|
||||
|
||||
Grab QUIK from the official [github releases page](https://github.com/octoshrimpy/quik/releases), or keep up with updates with the following:
|
||||
|
||||
|
||||
<a href="https://f-droid.org/repository/browse/?fdid=dev.octoshrimpy.quik.fdroid"><img src="https://f-droid.org/badge/get-it-on.png" alt="Get it on F-Droid" height="100"></a>
|
||||
<a href="https://apps.obtainium.imranr.dev/redirect?r=obtainium://app/{%22id%22:%22dev.octoshrimpy.quik%22,%22url%22:%22https://github.com/octoshrimpy/quik%22,%22author%22:%22octoshrimpy%22,%22name%22:%22QUIK%22,%22additionalSettings%22:%22{\%22apkFilterRegEx\%22:\%22release\%22,\%22invertAPKFilter\%22:false,\%22about\%22:\%22QUIK%20is%20an%20open%20source%20replacement%20for%20the%20stock%20messaging%20app%20on%20Android.%20It%20is%20a%20continuation%20of%20QKSMS.\%22}%22}"><img src="https://raw.githubusercontent.com/ImranR98/Obtainium/b1c8ac6f2ab08497189721a788a5763e28ff64cd/assets/graphics/badge_obtainium.png" alt="Get it on Obtainium" height="100"></a>
|
||||
<a href="https://github.com/octoshrimpy/quik/releases">
|
||||
<img src="https://user-images.githubusercontent.com/69304392/148696068-0cfea65d-b18f-4685-82b5-329a330b1c0d.png"
|
||||
alt="Download from GitHub releases" height="100" /></a>
|
||||
<!--
|
||||
</a><a href="https://play.google.com/store/apps/details?id=dev.octoshrimpy.quik"><img src="https://play.google.com/intl/en_us/badges/images/generic/en_badge_web_generic.png" alt="Download on Google Play" height="100">
|
||||
-->
|
||||
|
||||
## Matrix Chat
|
||||
You can chat with the community over at [#quik-sms:matrix.org](https://matrix.to/#/#quik-sms:matrix.org)
|
||||
|
||||
## Reporting bugs
|
||||
|
||||
A great bug report contains a description of the problem and steps to reproduce the problem. We need to know what we're looking for and where to look for it.
|
||||
|
||||
When reporting a bug, please make sure to provide the following information:
|
||||
- Steps to reproduce the issue
|
||||
- QUIK version
|
||||
- Device / OS information
|
||||
|
||||
## Contributing
|
||||
Contributions are very welcome! Please see the [contributing guidelines](/CONTRIBUTING.md) for details.
|
||||
|
||||
## Translations
|
||||
If you'd like to add translations to QUIK, please join the project on [Weblate](https://hosted.weblate.org/engage/quik/)! Translations that are committed directly to source files will not be accepted. For more information see the [translation guidelines](/CONTRIBUTING.md#translate).
|
||||
|
||||
<a href="https://hosted.weblate.org/engage/quik/">
|
||||
<img src="https://hosted.weblate.org/widget/quik/multi-auto.svg" alt="Translation status" />
|
||||
</a>
|
||||
|
||||
## Thank you
|
||||
|
||||
A special thank you to Jake ([@klinker41](https://github.com/klinker41)) and Luke Klinker ([@klinker24](https://github.com/klinker24)) for their work on [android-smsmms](https://github.com/klinker41/android-smsmms), which has been an unspeakably large help in implementing MMS into QUIK.
|
||||
|
||||
A giant thank you to Moez [moezbhatti](https://github.com/moezbhatti) for creating and maintaining QKSMS, of which QUIK would not exist without.
|
||||
|
||||
## Contact
|
||||
|
||||
QUIK is developed and maintained by [Marcos Jones](https://github.com/octoshrimpy).
|
||||
|
||||
---
|
||||
|
||||
## Star History
|
||||
|
||||
<a href="https://star-history.dera.page/#quik-sms/quik&type=Date">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://star-history.dera.page/svg?repos=quik-sms/quik&type=Date&theme=dark" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://star-history.dera.page/svg?repos=quik-sms/quik&type=Date" />
|
||||
<img alt="Star History Chart" src="https://star-history.dera.page/svg?repos=quik-sms/quik&type=Date" />
|
||||
</picture>
|
||||
</a>
|
||||
|
||||
---
|
||||
|
||||
<!-- <a href="https://liberapay.com/octoshrimpy/donate"><img alt="Donate using Liberapay" src="https://img.shields.io/badge/Liberapay-F6C915?style=for-the-badge&logo=liberapay&logoColor=black"></a> -->
|
||||
<a style="background-color: #5e40c2;" href="https://ko-fi.com/octoshrimpy/donate"><img alt="Donate using Ko-Fi" src="https://img.shields.io/badge/Ko--fi-F16061?style=for-the-badge&logo=ko-fi&logoColor=white"></a>
|
||||
<a href="https://patreon.com/octoshrimpy"><img alt="Donate using Patreon" src="https://img.shields.io/badge/Patreon-F96854?style=for-the-badge&logo=patreon&logoColor=white"></a>
|
||||
|
||||
## License
|
||||
|
||||
QUIK is released under the **The GNU General Public License v3.0 (GPLv3)**, which can be found in the [LICENSE](LICENSE) file in the root of this project.
|
||||
|
||||
## Automated release checks
|
||||
### Automated release checks
|
||||
|
||||
The workflow pins JDK 17 so test and build tools use the same Java runtime.
|
||||
Before building or publishing APKs, Gitea Actions runs Robolectric tests against the actual
|
||||
@@ -207,3 +143,27 @@ python3 .gitea/scripts/check_test_results.py
|
||||
The gate rejects failures, missing required suites, and skipped critical tests. A failed gate
|
||||
stops the workflow before publication. These tests cover known regression scenarios; they do
|
||||
not replace testing the installed Release APK on Android devices.
|
||||
|
||||
## Upstream maintenance
|
||||
|
||||
The [sync workflow](.gitea/workflows/sync.yml) runs weekly and on manual dispatch, merging `master` from the configured Gitea upstream mirror. Merge or sync failures are reported by the workflow.
|
||||
|
||||
After each upstream merge, review SMS/Matrix forwarding, reset and history import behavior, and signing configuration. Run the regression checks described above. Keep this fork's README separate from the inherited documentation; refresh `README.upstream.md` from upstream when needed and retain its credits and license notices.
|
||||
|
||||
## Documentation
|
||||
|
||||
- [Inherited upstream README](README.upstream.md): retained from this checkout, with fork-specific release checks moved here and repository-relative contribution links corrected.
|
||||
- [Upstream contribution guidelines](CONTRIBUTING.md).
|
||||
- [Privacy notice](PRIVACY).
|
||||
|
||||
[README style guide](docs/README-STYLE.md).
|
||||
|
||||
## Credits
|
||||
|
||||
Development of the changes maintained in this fork was carried out to a significant extent with assistance from AI coding agents, in collaboration with the repository owner.
|
||||
|
||||
QUIK continues QKSMS and includes work by the QUIK, Remotrix, and android-smsmms contributors. See [upstream acknowledgments](README.upstream.md#thank-you). Fork-specific issues belong in this fork's issue tracker.
|
||||
|
||||
## License
|
||||
|
||||
GNU General Public License v3.0; see [LICENSE](LICENSE). Upstream code and notices retain their original attribution.
|
||||
|
||||
@@ -0,0 +1,93 @@
|
||||

|
||||
|
||||
# QUIK
|
||||
|
||||
[](https://github.com/octoshrimpy/quik/actions/workflows/manual-release.yml)
|
||||
<a href="https://hosted.weblate.org/engage/quik/"><img src="https://hosted.weblate.org/widget/quik/svg-badge.svg" alt="Translation status" /></a>
|
||||
[](https://deepwiki.com/octoshrimpy/quik)
|
||||
|
||||
QUIK is an open source replacement to the [stock messaging app](https://github.com/android/platform_packages_apps_mms) on Android. It is a continuation of [QKSMS](https://github.com/moezbhatti/qksms).
|
||||
|
||||
## Features
|
||||
|
||||
- Scheduled messages
|
||||
- Message backup
|
||||
- Speech-to-text and text-to-speech integrated within the app
|
||||
- Message blocking and archiving
|
||||
- Voice messages
|
||||
- Attachments of any type of file
|
||||
- Message sorting
|
||||
- Message pinning
|
||||
- Delayed sending
|
||||
- Quick reply from notifications
|
||||
- Swipe actions
|
||||
- Emoji reaction handling
|
||||
- and much, much more
|
||||
|
||||
## Download
|
||||
|
||||
Grab QUIK from the official [github releases page](https://github.com/octoshrimpy/quik/releases), or keep up with updates with the following:
|
||||
|
||||
|
||||
<a href="https://f-droid.org/repository/browse/?fdid=dev.octoshrimpy.quik.fdroid"><img src="https://f-droid.org/badge/get-it-on.png" alt="Get it on F-Droid" height="100"></a>
|
||||
<a href="https://apps.obtainium.imranr.dev/redirect?r=obtainium://app/{%22id%22:%22dev.octoshrimpy.quik%22,%22url%22:%22https://github.com/octoshrimpy/quik%22,%22author%22:%22octoshrimpy%22,%22name%22:%22QUIK%22,%22additionalSettings%22:%22{\%22apkFilterRegEx\%22:\%22release\%22,\%22invertAPKFilter\%22:false,\%22about\%22:\%22QUIK%20is%20an%20open%20source%20replacement%20for%20the%20stock%20messaging%20app%20on%20Android.%20It%20is%20a%20continuation%20of%20QKSMS.\%22}%22}"><img src="https://raw.githubusercontent.com/ImranR98/Obtainium/b1c8ac6f2ab08497189721a788a5763e28ff64cd/assets/graphics/badge_obtainium.png" alt="Get it on Obtainium" height="100"></a>
|
||||
<a href="https://github.com/octoshrimpy/quik/releases">
|
||||
<img src="https://user-images.githubusercontent.com/69304392/148696068-0cfea65d-b18f-4685-82b5-329a330b1c0d.png"
|
||||
alt="Download from GitHub releases" height="100" /></a>
|
||||
<!--
|
||||
</a><a href="https://play.google.com/store/apps/details?id=dev.octoshrimpy.quik"><img src="https://play.google.com/intl/en_us/badges/images/generic/en_badge_web_generic.png" alt="Download on Google Play" height="100">
|
||||
-->
|
||||
|
||||
## Matrix Chat
|
||||
You can chat with the community over at [#quik-sms:matrix.org](https://matrix.to/#/#quik-sms:matrix.org)
|
||||
|
||||
## Reporting bugs
|
||||
|
||||
A great bug report contains a description of the problem and steps to reproduce the problem. We need to know what we're looking for and where to look for it.
|
||||
|
||||
When reporting a bug, please make sure to provide the following information:
|
||||
- Steps to reproduce the issue
|
||||
- QUIK version
|
||||
- Device / OS information
|
||||
|
||||
## Contributing
|
||||
Contributions are very welcome! Please see the [contributing guidelines](CONTRIBUTING.md) for details.
|
||||
|
||||
## Translations
|
||||
If you'd like to add translations to QUIK, please join the project on [Weblate](https://hosted.weblate.org/engage/quik/)! Translations that are committed directly to source files will not be accepted. For more information see the [translation guidelines](CONTRIBUTING.md#translate).
|
||||
|
||||
<a href="https://hosted.weblate.org/engage/quik/">
|
||||
<img src="https://hosted.weblate.org/widget/quik/multi-auto.svg" alt="Translation status" />
|
||||
</a>
|
||||
|
||||
## Thank you
|
||||
|
||||
A special thank you to Jake ([@klinker41](https://github.com/klinker41)) and Luke Klinker ([@klinker24](https://github.com/klinker24)) for their work on [android-smsmms](https://github.com/klinker41/android-smsmms), which has been an unspeakably large help in implementing MMS into QUIK.
|
||||
|
||||
A giant thank you to Moez [moezbhatti](https://github.com/moezbhatti) for creating and maintaining QKSMS, of which QUIK would not exist without.
|
||||
|
||||
## Contact
|
||||
|
||||
QUIK is developed and maintained by [Marcos Jones](https://github.com/octoshrimpy).
|
||||
|
||||
---
|
||||
|
||||
## Star History
|
||||
|
||||
<a href="https://star-history.dera.page/#quik-sms/quik&type=Date">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://star-history.dera.page/svg?repos=quik-sms/quik&type=Date&theme=dark" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://star-history.dera.page/svg?repos=quik-sms/quik&type=Date" />
|
||||
<img alt="Star History Chart" src="https://star-history.dera.page/svg?repos=quik-sms/quik&type=Date" />
|
||||
</picture>
|
||||
</a>
|
||||
|
||||
---
|
||||
|
||||
<!-- <a href="https://liberapay.com/octoshrimpy/donate"><img alt="Donate using Liberapay" src="https://img.shields.io/badge/Liberapay-F6C915?style=for-the-badge&logo=liberapay&logoColor=black"></a> -->
|
||||
<a style="background-color: #5e40c2;" href="https://ko-fi.com/octoshrimpy/donate"><img alt="Donate using Ko-Fi" src="https://img.shields.io/badge/Ko--fi-F16061?style=for-the-badge&logo=ko-fi&logoColor=white"></a>
|
||||
<a href="https://patreon.com/octoshrimpy"><img alt="Donate using Patreon" src="https://img.shields.io/badge/Patreon-F96854?style=for-the-badge&logo=patreon&logoColor=white"></a>
|
||||
|
||||
## License
|
||||
|
||||
QUIK is released under the **The GNU General Public License v3.0 (GPLv3)**, which can be found in the [LICENSE](LICENSE) file in the root of this project.
|
||||
@@ -0,0 +1,74 @@
|
||||
# Repository README standard
|
||||
|
||||
Version: 1.0. Documentation language: English.
|
||||
|
||||
A README should explain the project, help a new reader start it, and point to detailed references. Keep project-specific instructions and existing attribution when applying this standard.
|
||||
|
||||
## Original projects
|
||||
|
||||
Start with one `# Project name` heading and a short description of what the project does and who it serves. An optional local screenshot or banner may follow. Then add a navigation line linking to the level-two sections present in the document.
|
||||
|
||||
Use these level-two headings in this order. Omit sections that do not apply; do not add empty sections or filler just to match the template.
|
||||
|
||||
| Section | Content |
|
||||
| --- | --- |
|
||||
| Features | Concrete capabilities and supported use cases. |
|
||||
| Requirements | Runtime, hardware, services, and build prerequisites; distinguish build from runtime needs. |
|
||||
| Getting started | Shortest complete path from checkout or download to a working result, including initial setup. |
|
||||
| Configuration | Settings, defaults, required values, and example files. Explain prerequisites before commands that need them. |
|
||||
| Usage | Common workflows, commands, and expected output or artifact locations. |
|
||||
| Architecture | Project layout, interfaces, data model, or hardware overview. |
|
||||
| Limitations | Known constraints and validation boundaries; keep critical setup constraints near the affected step too. |
|
||||
| Development | Build, test, validation, and release instructions supported by repository files. |
|
||||
| Documentation | Links to detailed guides, diagrams, screenshots, and this style guide. |
|
||||
| Credits | Contributors, reused work, upstream sources, and existing AI-assistance disclosures. |
|
||||
| License | Link to the actual project license; state explicitly when no project-level license file exists. |
|
||||
|
||||
Keep specialized content under these headings using `###` and `####`. For example, put power variants under Configuration, pinouts under Architecture, and schematic downloads under Documentation or Architecture. Small component READMEs can use only the relevant sections and link back to the root README.
|
||||
|
||||
## Forks
|
||||
|
||||
Use the same formatting rules, but introduce the fork before describing the original project. Start with one title, a short fork description, and clearly labeled links to upstream and the fork repository.
|
||||
|
||||
Use these headings in order, omitting optional sections when unnecessary:
|
||||
|
||||
1. Fork purpose
|
||||
2. Changes from upstream
|
||||
3. Requirements
|
||||
4. Getting started
|
||||
5. Configuration
|
||||
6. Usage
|
||||
7. Architecture
|
||||
8. Limitations
|
||||
9. Development
|
||||
10. Upstream maintenance
|
||||
11. Documentation
|
||||
12. Credits
|
||||
13. License
|
||||
|
||||
Explain why the fork exists, list its differences, and identify where to obtain its builds. Clearly label links to upstream builds, contribution channels, and screenshots. Include upstream synchronization instructions based on the actual workflow, and checks needed after merges.
|
||||
|
||||
Keep inherited documentation in `README.upstream.md` at the repository root. Keeping it beside the original README preserves relative links to assets. Retain upstream attribution, donations, and license notices there. Label any local corrections; this file is inherited documentation, not a claim to be the latest upstream version. After an upstream merge, refresh the inherited file and review the fork README separately. Do not overwrite the fork's explanation with the upstream README.
|
||||
|
||||
Borrowing a component or taking inspiration from another project does not by itself make the entire repository a fork. Explain that relationship under Credits and preserve component licensing.
|
||||
|
||||
## Markdown and accuracy
|
||||
|
||||
- Write documentation in English. Preserve proper names and UI labels as shown in the product.
|
||||
- Use one H1, sentence-case headings, and consecutive heading levels. Do not number headings.
|
||||
- Separate paragraphs, headings, lists, tables, and fenced blocks with blank lines.
|
||||
- Use `-` for unordered lists. Indent nested content consistently; use four spaces for nested unordered lists.
|
||||
- Label fenced blocks: `bash`, `sh`, `powershell`, `python`, `json`, `yaml`, `dotenv`, `text`, or `mermaid` as appropriate.
|
||||
- Run commands from the repository root unless a different working directory is explicitly stated.
|
||||
- Use placeholders or portable example paths instead of private workstation paths. Never include real tokens, passwords, private keys, or local data.
|
||||
- Link to versioned files using relative paths. Use full URLs for other repositories, services, and upstream sources. Avoid sibling-checkout links.
|
||||
- Prefer Markdown. Use HTML only when it improves a gallery or layout; provide image alt text.
|
||||
- Keep navigation anchors synchronized with headings. Avoid duplicate headings that create ambiguous anchors.
|
||||
- Avoid decorative badges, repeated separators, promotional claims, and unsupported claims of production readiness or completed testing.
|
||||
- Verify requirements and commands against manifests, scripts, configuration, and workflows. Distinguish previously documented results from checks performed during an edit.
|
||||
- Preserve existing technical instructions, screenshots, credits, and license notices when reorganizing. Move long references into `docs/` when useful and update links relative to their new location.
|
||||
- Never infer a license from a badge, framework, dependency, or a different repository. License choices require an explicit project decision.
|
||||
|
||||
## Maintenance
|
||||
|
||||
Update the README alongside changes to installation, configuration, commands, supported hardware, or release behavior. Check local links, navigation, and Markdown structure before committing. Run a command only when its effects are appropriate; a documentation check must not flash hardware, publish a release, send messages, or start an import.
|
||||
Reference in New Issue
Block a user