diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 0000000..fe21cd6 --- /dev/null +++ b/docs/ROADMAP.md @@ -0,0 +1,83 @@ +# BOS Project Roadmap + +This document outlines the development phases for BOS (Bugema Operating System), +a free, open-source, self-hostable internet OS. + +## Vision + +BOS aims to provide a unified, browser-based operating system experience that +individuals and organizations can host on their own infrastructure. It connects +the broader Bugema Open Source Community (BOSC) ecosystem — including +GreenCode, OpenCare-Core, and LifeLine-ICT — under a single platform. + +--- + +## Phase 1: Documentation & Governance Foundations *(Current)* + +**Goal:** Establish the contributor experience and project governance so the +community can grow sustainably. + +| Milestone | Status | +|------------------------------------|--------------| +| Expand README with project overview | 🔄 In Progress | +| Add CONTRIBUTING.md | 🔄 In Progress | +| Define Code of Conduct | ⬜ Planned | +| Create issue and PR templates | ⬜ Planned | +| Document architecture decisions | 🔄 In Progress | +| Choose and document license | ✅ Done (MIT) | + +--- + +## Phase 2: Core OS Abstractions & API Design + +**Goal:** Define the application model, file system abstraction, and user +management APIs that form the kernel of BOS. + +| Milestone | Status | +|------------------------------------------------|------------| +| Design user authentication and session model | ⬜ Planned | +| Define virtual file system API | ⬜ Planned | +| Create application manifest specification | ⬜ Planned | +| Build REST API for app lifecycle management | ⬜ Planned | +| Implement basic permission and role system | ⬜ Planned | + +--- + +## Phase 3: Application Ecosystem Integration + +**Goal:** Integrate BOSC projects as first-class BOS applications and enable +third-party app development. + +| Milestone | Status | +|------------------------------------------------|------------| +| Package GreenCode as a BOS application | ⬜ Planned | +| Package OpenCare-Core as a BOS application | ⬜ Planned | +| Package LifeLine-ICT as a BOS application | ⬜ Planned | +| Create app developer SDK and documentation | ⬜ Planned | +| Build app marketplace / registry | ⬜ Planned | + +--- + +## Phase 4: Self-Hosting & Deployment Tooling + +**Goal:** Make BOS easy to deploy on personal servers, cloud VMs, or +institutional infrastructure. + +| Milestone | Status | +|------------------------------------------------|------------| +| Docker Compose single-command deployment | ⬜ Planned | +| Automated backup and restore tooling | ⬜ Planned | +| HTTPS and reverse proxy configuration guide | ⬜ Planned | +| Resource monitoring and health dashboards | ⬜ Planned | +| Multi-tenant support | ⬜ Planned | + +--- + +## How to Contribute + +Pick a milestone from the current phase and open an issue describing your +proposed approach. See [CONTRIBUTING.md](../CONTRIBUTING.md) for workflow +details. + +Significant design changes should be captured as Architecture Decision Records +in `docs/adr/`. diff --git a/docs/adr/001-mit-license.md b/docs/adr/001-mit-license.md new file mode 100644 index 0000000..ad61425 --- /dev/null +++ b/docs/adr/001-mit-license.md @@ -0,0 +1,46 @@ +# ADR-001: MIT License Selection + +## Status + +Accepted + +## Date + +2025-01-01 + +## Context + +BOS is an educational and community-driven project created by the Bugema Open +Source Community. The project needs a license that: + +- Allows free use, modification, and distribution +- Is simple enough for student contributors to understand +- Does not impose copyleft obligations that might discourage adoption by + institutions or companies +- Is widely recognized and compatible with most other open-source licenses + +## Decision + +We chose the **MIT License** for BOS and its sub-projects. + +The MIT License is one of the most permissive open-source licenses. It imposes +minimal restrictions — users must include the copyright notice and license text +in copies — but otherwise allows commercial use, modification, distribution, +and private use without restriction. + +## Consequences + +**Positive:** +- Low barrier to adoption — anyone can use BOS without legal concerns +- Compatible with virtually all other open-source licenses +- Simple text that student contributors can read and understand +- Widely used in the JavaScript, Python, and Java ecosystems the project + depends on + +**Trade-offs:** +- No copyleft protection — third parties can create proprietary forks +- No patent grant (unlike Apache 2.0) +- Contributors' modifications can be closed-sourced by downstream users + +These trade-offs are acceptable for an educational project focused on community +learning and collaboration. diff --git a/docs/adr/002-documentation-first.md b/docs/adr/002-documentation-first.md new file mode 100644 index 0000000..5afb381 --- /dev/null +++ b/docs/adr/002-documentation-first.md @@ -0,0 +1,47 @@ +# ADR-002: Documentation-First Development Approach + +## Status + +Accepted + +## Date + +2025-01-15 + +## Context + +BOS is in its early stages with a small contributor base of university students. +The temptation is to jump directly into coding, but early-stage projects +without documentation tend to accumulate technical debt and lose contributors +who cannot understand the codebase. + +The Bugema Open Source Community (BOSC) uses its projects as learning platforms, +so contributor onboarding is a primary concern. + +## Decision + +We adopt a **documentation-first development approach**: before implementing a +feature, contributors must first document the design, API contracts, and +expected behavior. Code PRs should be preceded (or accompanied) by +documentation PRs. + +In practice this means: + +1. New features start as an issue describing the problem and proposed solution. +2. An architecture decision record (ADR) is created for significant design + choices. +3. API endpoints are documented before implementation begins. +4. README and setup guides are updated as part of every feature PR. + +## Consequences + +**Positive:** +- New contributors can understand the project without reading all the code +- Design flaws are caught during documentation review, before code is written +- The project builds a knowledge base that survives contributor turnover +- Aligns with the educational mission of BOSC + +**Trade-offs:** +- Slower initial velocity — writing docs before code takes more time upfront +- Risk of documentation drift if docs are not updated alongside code changes +- Requires discipline from all contributors, including reviewers diff --git a/docs/adr/template.md b/docs/adr/template.md new file mode 100644 index 0000000..89ef44a --- /dev/null +++ b/docs/adr/template.md @@ -0,0 +1,28 @@ +# ADR Template + +Use this template when recording significant architectural decisions. + +## Title + +**ADR-NNN: [Short descriptive title]** + +## Status + +[Proposed | Accepted | Deprecated | Superseded by ADR-NNN] + +## Date + +YYYY-MM-DD + +## Context + +Describe the forces at play, the problem being solved, and any constraints. + +## Decision + +State the decision that was made and the rationale. + +## Consequences + +Describe the resulting context after applying the decision. Include both +positive outcomes and trade-offs.