diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index aba56dd..b1eb727 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,28 +2,33 @@ First off, thank you for considering contributing to Sovran_SystemsOS! 🎉 -## This GitHub Repo +## Development and Release Repositories -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 -([`stable` branch](https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsOS/src/branch/stable)), -as the ethos of Sovran_SystemsOS is self-sovereignty. +The GitHub repository is the primary location for Sovran_SystemsOS development +and collaboration and serves as the project's connection to the GitHub +ecosystem. Most work is contributed through feature branches and pull requests +that target GitHub `main`. Development may also begin in a local branch or on +`staging-dev` at the project's self-hosted Gitea instance: +https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsOS. + +GitHub `main` and Gitea `staging-dev` are kept synchronized as the active +development line, although one may briefly lead the other while changes are +being integrated. The canonical, release-ready code is maintained on Gitea's +[`stable` branch](https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsOS/src/branch/stable), +in keeping with the self-sovereignty ethos of Sovran_SystemsOS. The workflow is: -1. Development happens on the `staging-dev` branch on Gitea, which the GitHub - repository mirrors. -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. +1. Most development and project collaboration — including issues, pull + requests, and reviews — happens through GitHub, with completed work + integrated into `main`. +2. Work may also originate locally or on Gitea `staging-dev`. Accepted changes + are synchronized between GitHub `main` and Gitea `staging-dev`. +3. When changes are complete and tested, they are promoted to Gitea `stable`, + which is the code used by released Sovran_SystemsOS builds. -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. +Please note: GitHub `main` and Gitea `staging-dev` may contain new features and +code not yet in `stable`, and that code may not be 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 c282870..0a21006 100644 --- a/README.md +++ b/README.md @@ -31,16 +31,19 @@ are ready. -> **📌 Development mirror — stable releases live on Gitea** +> **📌 Active development — stable releases live on Gitea** > -> 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 -> there, and once complete they are moved to the `stable` branch on +> Most development and collaboration happens through the +> [GitHub repository](https://github.com/naturallaw777/Sovran_SystemsOS), with +> changes integrated into its `main` branch. Work may also begin locally or on +> the `staging-dev` branch of the project's self-hosted Gitea instance. GitHub +> `main` and Gitea `staging-dev` are kept synchronized as the active development +> line. Once changes are complete and tested, they are promoted 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 the GitHub -> repository may be newer and less tested than the Gitea `stable` branch. -> See [Development workflow](#development-workflow) for details. +> — the canonical, release-ready home of Sovran_SystemsOS. Development code may +> be newer and less tested than Gitea `stable`. See +> [Development workflow](#development-workflow) for details. --- @@ -468,30 +471,35 @@ optional self-hosting services are all maintained in this repository. ### Development workflow -Sovran_SystemsOS development is split across two repositories: +Sovran_SystemsOS uses two hosted repositories, as well as local development +branches: +- **[GitHub](https://github.com/naturallaw777/Sovran_SystemsOS)** — the primary + location for development and collaboration and the project's connection to + the GitHub ecosystem. Most feature branches and pull requests target its + `main` branch. - **[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](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. + Its `staging-dev` branch is part of the active development line and can also + receive development work. Its + [`stable` branch](https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsOS/src/branch/stable) + holds the tested, release-ready code. -The workflow is: +Development can begin on GitHub, on Gitea `staging-dev`, or in a local branch. +In practice: -1. Development happens on the `staging-dev` branch on Gitea, which the GitHub - repository mirrors. -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. +1. Most development and project collaboration — including issues, pull + requests, and reviews — happens through GitHub, with completed work + integrated into `main`. +2. Accepted changes are synchronized between GitHub `main` and Gitea + `staging-dev`, so together they represent the active development line. One + may briefly lead the other while changes are being integrated. +3. When changes are complete and tested, they are promoted to the `stable` + branch on Gitea, which is the code used by released Sovran_SystemsOS builds. -> ⚠️ 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 +> ⚠️ GitHub `main` and Gitea `staging-dev` 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 @@ -521,8 +529,9 @@ git clone -b stable https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsO cd Sovran_SystemsOS ``` -or clone the **development mirror** from GitHub, which tracks Gitea's -`staging-dev` branch and may contain untested changes: +or clone the **active development code** from GitHub. GitHub `main` and Gitea +`staging-dev` are kept synchronized and may contain changes that are not yet +fully tested or released: ```bash git clone https://github.com/naturallaw777/Sovran_SystemsOS.git @@ -816,11 +825,11 @@ Read the complete license terms in [`LICENSE`](LICENSE). 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. +primary location for development and collaboration. Its `main` branch is kept +synchronized with `staging-dev` on the self-hosted +[Gitea instance](https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsOS), +where the `stable` branch holds tested, release-ready code. Please read our +[Contributing Guidelines](CONTRIBUTING.md) before submitting a pull request.