From ec43d631d4b32d8f0698b0ce69021e21ecd918ac Mon Sep 17 00:00:00 2001 From: naturallaw777 <99053422+naturallaw777@users.noreply.github.com> Date: Tue, 4 Aug 2026 16:39:27 +0000 Subject: [PATCH 1/2] docs: clarify GitHub is the dev mirror of the Gitea stable repo The GitHub repo mirrors Gitea's staging-dev branch; changes are tested here and promoted to the stable branch on the self-hosted Gitea instance. Co-authored-by: arena-agent <297053741+arena-agent@users.noreply.github.com> --- CONTRIBUTING.md | 23 ++++++++++++++++--- README.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 79 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0c67aca..2ce8249 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,11 +2,28 @@ First off, thank you for considering contributing to Sovran_SystemsOS! 🎉 -## This Github Repo +## This GitHub Repo -This repo is for the development of Sovran_SystemsOS and serves as its connection to the GitHub ecosystem. The main repo for Sovran_SystemsOS is hosted at https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsOS/src/branch/stable. All activity in this GitHub repo is tested and eventually mirrored to the main repo on Gitea, as the ethos of Sovran_SystemsOS is self-sovereignty. +This repository is the **development mirror** of Sovran_SystemsOS and serves as +its connection to the GitHub ecosystem. The **main, stable repository** is +self-hosted on the project's Gitea instance at +https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsOS +([`stable` branch](https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsOS/src/branch/stable)), +as the ethos of Sovran_SystemsOS is self-sovereignty. -Please note: this repo may contain new features and code not yet in the stable branch on Gitea, and this code is not fully tested. +The workflow is: + +1. Development happens on the `staging-dev` branch on Gitea, which this GitHub + repository mirrors. +2. All activity in this GitHub repo — issues, pull requests, reviews, and + testing — is done against the mirrored `staging-dev` code. +3. When changes are complete and tested, they are moved to the `stable` branch + on the Gitea instance, which is the code used by released Sovran_SystemsOS + builds. + +Please note: this repo mirrors `staging-dev`, so it may contain new features +and code not yet in the `stable` branch on Gitea, and this code is not fully +tested. Moreover, Sovran_SystemsOS has been improved with the help of AI. We have used Copilot and Arean.Ai to work through significant coding challenges and troubleshooting hurdles. We will continue to use AI to help keep Sovran_SystemsOS stable and maintained. diff --git a/README.md b/README.md index 376879d..a2bc000 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,16 @@ are ready. +> **📌 Development mirror — stable releases live on Gitea** +> +> This GitHub repository is for **development**. It mirrors the `staging-dev` +> branch from the project's self-hosted Gitea instance. Changes are tested +> here, and once complete they are moved to the `stable` branch on +> [git.sovransystems.com](https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsOS/src/branch/stable) +> — the canonical, release-ready home of Sovran_SystemsOS. Code in this +> repository may be newer and less tested than the Gitea `stable` branch. +> See [Development workflow](#development-workflow) for details. + --- ## Contents @@ -42,6 +52,8 @@ are ready. - [The Sovran Hub](#the-sovran-hub) - [Install Sovran_SystemsOS](#install-sovran_systemsos) - [For developers](#for-developers) + - [Development workflow](#development-workflow) + - [Build from source](#build-from-source) - [About Bitcoin wallet entropy](#about-bitcoin-wallet-entropy) - [Security approach](#security-approach) - [Acknowledgements](#acknowledgements) @@ -453,6 +465,34 @@ Sovran Hub into a complete Bitcoin operating system. The operating system configuration, installer, Hub, desktop integration, Bitcoin services, and optional self-hosting services are all maintained in this repository. +### Development workflow + +Sovran_SystemsOS development is split across two repositories: + +- **[git.sovransystems.com (self-hosted Gitea)](https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsOS)** — the + canonical home of the project, in keeping with the ethos of self-sovereignty. + Its [`stable` branch](https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsOS/src/branch/stable) + holds the tested, release-ready code, and its `staging-dev` branch holds + work in progress. +- **[GitHub (this repository)](https://github.com/naturallaw777/Sovran_SystemsOS)** — the + development mirror and the project's connection to the GitHub ecosystem. It + mirrors the `staging-dev` branch from Gitea. + +The workflow is: + +1. Development happens on the `staging-dev` branch on Gitea, which this GitHub + repository mirrors. +2. All activity in this GitHub repository — issues, pull requests, reviews, + and testing — is done against the mirrored `staging-dev` code. +3. When changes are complete and tested, they are moved to the `stable` branch + on the Gitea instance, which is the code used by released + Sovran_SystemsOS builds. + +> ⚠️ Because this repository tracks `staging-dev`, it may contain new features +> and code that are not yet fully tested or released. For the current stable, +> audited code, use the `stable` branch on +> [git.sovransystems.com](https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsOS/src/branch/stable). + ### Technology - [NixOS](https://nixos.org) and [Nix flakes](https://nixos.wiki/wiki/Flakes) @@ -473,10 +513,24 @@ optional self-hosting services are all maintained in this repository. You need a system with Nix installed and flakes enabled. +Clone the **stable** code from the self-hosted Gitea instance (recommended): + +```bash +git clone -b stable https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsOS.git +cd Sovran_SystemsOS +``` + +or clone the **development mirror** from GitHub (this repository), which +tracks Gitea's `staging-dev` branch and may contain untested changes: + ```bash git clone https://github.com/naturallaw777/Sovran_SystemsOS.git cd Sovran_SystemsOS +``` +Then build the installer ISO: + +```bash nix build \ .#nixosConfigurations.sovran_systemsos-iso.config.system.build.isoImage ``` @@ -759,7 +813,11 @@ Read the complete license terms in [`LICENSE`](LICENSE). ## Contributing -We welcome contributions! Please read our [Contributing Guidelines](CONTRIBUTING.md) before submitting a pull request. +We welcome contributions! This GitHub repository is the **development mirror** +— the stable, tested releases are maintained on the `stable` branch of the +self-hosted [Gitea instance](https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsOS). +Please read our [Contributing Guidelines](CONTRIBUTING.md) before submitting a +pull request.
From 7b381d03870773fe6e5a1c1bb5f0b9c3d13842e0 Mon Sep 17 00:00:00 2001 From: naturallaw777 <99053422+naturallaw777@users.noreply.github.com> Date: Tue, 4 Aug 2026 17:03:52 +0000 Subject: [PATCH 2/2] docs: make repo references mirror-neutral for Gitea readers The README and CONTRIBUTING are mirrored to both Gitea branches, so GitHub-specific references now name the GitHub repository explicitly instead of saying 'this repository'. Co-authored-by: arena-agent <297053741+arena-agent@users.noreply.github.com> --- CONTRIBUTING.md | 10 +++++----- README.md | 31 +++++++++++++++++-------------- 2 files changed, 22 insertions(+), 19 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2ce8249..aba56dd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,7 @@ First off, thank you for considering contributing to Sovran_SystemsOS! 🎉 ## This GitHub Repo -This repository is the **development mirror** of Sovran_SystemsOS and serves as +The GitHub repository is the **development mirror** of Sovran_SystemsOS and serves as its connection to the GitHub ecosystem. The **main, stable repository** is self-hosted on the project's Gitea instance at https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsOS @@ -13,15 +13,15 @@ as the ethos of Sovran_SystemsOS is self-sovereignty. The workflow is: -1. Development happens on the `staging-dev` branch on Gitea, which this GitHub +1. Development happens on the `staging-dev` branch on Gitea, which the GitHub repository mirrors. -2. All activity in this GitHub repo — issues, pull requests, reviews, and +2. All activity in the GitHub repo — issues, pull requests, reviews, and testing — is done against the mirrored `staging-dev` code. 3. When changes are complete and tested, they are moved to the `stable` branch on the Gitea instance, which is the code used by released Sovran_SystemsOS builds. -Please note: this repo mirrors `staging-dev`, so it may contain new features +Please note: the GitHub repo mirrors `staging-dev`, so it may contain new features and code not yet in the `stable` branch on Gitea, and this code is not fully tested. @@ -43,7 +43,7 @@ Moreover, Sovran_SystemsOS has been improved with the help of AI. We have used C ### 🔧 Submitting Code Changes #### 1. Fork the Repository -Click the "Fork" button at the top right of this repository. +Click the "Fork" button at the top right of the GitHub repository. #### 2. Clone Your Fork ```bash diff --git a/README.md b/README.md index a2bc000..c282870 100644 --- a/README.md +++ b/README.md @@ -33,11 +33,12 @@ are ready. > **📌 Development mirror — stable releases live on Gitea** > -> This GitHub repository is for **development**. It mirrors the `staging-dev` +> The [GitHub repository](https://github.com/naturallaw777/Sovran_SystemsOS) is +> the **development mirror** of this project. It mirrors the `staging-dev` > branch from the project's self-hosted Gitea instance. Changes are tested -> here, and once complete they are moved to the `stable` branch on +> there, and once complete they are moved to the `stable` branch on > [git.sovransystems.com](https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsOS/src/branch/stable) -> — the canonical, release-ready home of Sovran_SystemsOS. Code in this +> — the canonical, release-ready home of Sovran_SystemsOS. Code in the GitHub > repository may be newer and less tested than the Gitea `stable` branch. > See [Development workflow](#development-workflow) for details. @@ -474,23 +475,23 @@ Sovran_SystemsOS development is split across two repositories: Its [`stable` branch](https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsOS/src/branch/stable) holds the tested, release-ready code, and its `staging-dev` branch holds work in progress. -- **[GitHub (this repository)](https://github.com/naturallaw777/Sovran_SystemsOS)** — the +- **[GitHub](https://github.com/naturallaw777/Sovran_SystemsOS)** — the development mirror and the project's connection to the GitHub ecosystem. It mirrors the `staging-dev` branch from Gitea. The workflow is: -1. Development happens on the `staging-dev` branch on Gitea, which this GitHub +1. Development happens on the `staging-dev` branch on Gitea, which the GitHub repository mirrors. -2. All activity in this GitHub repository — issues, pull requests, reviews, +2. All activity in the GitHub repository — issues, pull requests, reviews, and testing — is done against the mirrored `staging-dev` code. 3. When changes are complete and tested, they are moved to the `stable` branch on the Gitea instance, which is the code used by released Sovran_SystemsOS builds. -> ⚠️ Because this repository tracks `staging-dev`, it may contain new features -> and code that are not yet fully tested or released. For the current stable, -> audited code, use the `stable` branch on +> ⚠️ Because the GitHub repository tracks `staging-dev`, it may contain new +> features and code that are not yet fully tested or released. For the current +> stable, audited code, use the `stable` branch on > [git.sovransystems.com](https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsOS/src/branch/stable). ### Technology @@ -520,8 +521,8 @@ git clone -b stable https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsO cd Sovran_SystemsOS ``` -or clone the **development mirror** from GitHub (this repository), which -tracks Gitea's `staging-dev` branch and may contain untested changes: +or clone the **development mirror** from GitHub, which tracks Gitea's +`staging-dev` branch and may contain untested changes: ```bash git clone https://github.com/naturallaw777/Sovran_SystemsOS.git @@ -813,9 +814,11 @@ Read the complete license terms in [`LICENSE`](LICENSE). ## Contributing -We welcome contributions! This GitHub repository is the **development mirror** -— the stable, tested releases are maintained on the `stable` branch of the -self-hosted [Gitea instance](https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsOS). +We welcome contributions! The +[GitHub repository](https://github.com/naturallaw777/Sovran_SystemsOS) is the +**development mirror** — the stable, tested releases are maintained on the +`stable` branch of the self-hosted +[Gitea instance](https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsOS). Please read our [Contributing Guidelines](CONTRIBUTING.md) before submitting a pull request.