diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..e3ac180 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,29 @@ +--- +name: Bug report +about: Report a problem in BOS documentation, workflow, or future implementation +title: "[Bug] " +labels: bug +assignees: "" +--- + +## Summary + +Describe the bug clearly and briefly. + +## Current behavior + +What happens today? + +## Expected behavior + +What should happen instead? + +## Steps to reproduce + +1. +2. +3. + +## Additional context + +Include screenshots, logs, links, or notes if they help explain the issue. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..f8c4da1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,24 @@ +--- +name: Feature request +about: Suggest a new BOS capability, workflow, or documentation improvement +title: "[Feature] " +labels: enhancement +assignees: "" +--- + +## Problem + +What gap, pain point, or opportunity does this request address? + +## Proposed improvement + +Describe the feature, documentation update, or workflow improvement you want to +see. + +## Expected benefit + +Explain how this would help contributors, maintainers, or end users. + +## Notes + +Add examples, references, screenshots, or related issues if available. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e525dfc --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,82 @@ +# Contributing to BOS + +Thank you for helping shape BOS. This repository is still in an early, +documentation-first stage, so thoughtful planning, issue refinement, and clear +pull requests are just as valuable as code. + +## Before You Start + +- Check the open issues to avoid duplicating work. +- If no issue exists, open one that explains the problem, the proposed + improvement, and the expected benefit. +- Keep each pull request focused on one feature, fix, or documentation task. + +## Local Setup + +There is no application build pipeline in this repository yet. For now, the +main setup steps are: + +```bash +git clone https://github.com/bos-com/BOS.git +cd BOS +``` + +Use a Markdown-friendly editor and preview your documentation changes before +submitting them. + +## Branch Naming + +Use descriptive branch names that match the type of work being done: + +- `docs/` for documentation improvements +- `feat/` for new features or scaffolding +- `fix/` for bug fixes +- `chore/` for maintenance tasks + +Examples: + +- `docs/readme-quick-start` +- `feat/service-layout` +- `fix/broken-links` + +## Pull Request Expectations + +Each pull request should: + +- reference the related issue number, +- explain the problem being solved, +- summarize the change, +- describe how you verified it, and +- note any follow-up work that remains. + +If your change affects documentation or contributor workflow, include before and +after context so reviewers can quickly understand the improvement. + +## Documentation Standards + +- Prefer clear, direct language over placeholders. +- Keep setup instructions honest to the current repository state. +- Do not describe commands or services that do not yet exist in the repo. +- Use consistent Markdown headings and code fences. + +## Reporting Issues + +When opening an issue, include: + +- a short, specific title, +- the current problem or gap, +- the proposed improvement, +- why it matters, and +- any relevant screenshots, logs, or links. + +Starter issue templates are available in `.github/ISSUE_TEMPLATE/`. + +## Review Checklist + +Before opening a pull request, make sure: + +- the change is scoped to the issue, +- file names and headings are consistent, +- links and commands are correct, +- documentation reflects the real repository state, and +- the PR description includes verification notes. diff --git a/README.md b/README.md index 2973e74..a71e45d 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,90 @@ # BOS -BOS (Bugema Operating System) the internet OS! Free, Open Source, Self hostable + +BOS (Bugema Operating System) is a community-driven, self-hostable "internet +OS" focused on simplifying web services for campus and community use. + +## Project Overview + +BOS is intended to become a practical foundation for shared digital services +that schools, student communities, and local organisations can host for +themselves. The project emphasizes simple deployment, open collaboration, and a +workflow that helps new contributors learn by building in public. + +This repository is currently documentation-first. It captures the product +direction, contribution workflow, and starter conventions for future modules. +There is not yet a packaged installer or a runnable BOS application in this +repository. + +## Goals + +- Provide a lightweight, open platform for hosting shared services. +- Encourage contributions from students and community developers. +- Keep deployments simple and self-hostable. +- Establish a clear open-source workflow before the codebase expands. + +## Planned Scope + +The long-term BOS platform is expected to support: + +- campus and community web services, +- reusable admin and collaboration tools, +- self-hosted deployment patterns, and +- documentation that helps new contributors onboard quickly. + +## Repository Contents + +| Path | Purpose | +| --- | --- | +| `README.md` | High-level project overview and onboarding notes | +| `CONTRIBUTING.md` | Contribution workflow, branch naming, and PR guidance | +| `LICENSE` | Repository license | +| `.github/ISSUE_TEMPLATE/` | Starter issue templates for bugs and feature requests | + +## Quick Start + +Because BOS is still in a documentation-first phase, the quickest way to get +started is to contribute to the project structure and planning materials. + +1. Clone the repository: + + ```bash + git clone https://github.com/bos-com/BOS.git + cd BOS + ``` + +2. Review the current project direction in this README and the contribution + expectations in `CONTRIBUTING.md`. +3. Choose an existing issue or open a new one describing the gap you want to + address. +4. Create a focused branch, make your change, and open a pull request. + +## Local Requirements + +At the current project stage, contributors only need a lightweight toolchain: + +- Git for version control +- A GitHub account for issues and pull requests +- A text editor or IDE for Markdown and future code changes +- Optional: Markdown preview support to validate documentation updates + +## Contributor Workflow + +- Start from a clear issue or documented improvement. +- Keep changes scoped to one concern where possible. +- Document assumptions when the repository does not yet contain runnable code. +- Use pull requests to explain what problem was solved and how it was verified. + +Detailed conventions are documented in `CONTRIBUTING.md`. + +## Roadmap + +Near-term repository improvements include: + +- expanding architecture notes, +- documenting expected service modules, +- defining local development standards, and +- introducing starter implementation scaffolding for BOS components. + +## License + +This project is available under the terms described in [`LICENSE`](LICENSE).