init: moved to gumx.cc

1 files changed, 223 insertions, 0 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..7173170
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,223 @@
+---
+title: contributing guide
+---
+
+# contributing to ubergeek
+
+ubergeek is a community study guide. Contributions are welcome — fixes,
+improvements, new exercises, better explanations, and sample projects.
+
+The primary repository lives on **sourcehut** and is mirrored to GitHub and
+GitLab. You can contribute from any platform.
+
+---
+
+## Ways to Contribute
+
+- **Fix errors** — typos, incorrect information, broken examples
+- **Improve explanations** — clearer wording, better analogies, added context
+- **Add exercises and projects** — practice problems, mini-projects, challenge sets
+- **Add sample code** — working examples in any of the covered languages
+- **Add diagrams and images** — ASCII art, schematics, architecture diagrams
+- **Review existing content** — flag sections that are confusing or incomplete
+- **Suggest new topics or modules** — open a discussion first
+
+---
+
+## Repository Structure
+
+```
+topic-name/
+├── index.md                  # Topic overview
+├── images/                   # Diagrams, schematics, screenshots (.png, .svg, .jpg)
+├── samples/                  # Runnable code and project files
+│   └── project-name/
+│       ├── src/
+│       ├── Makefile
+│       └── README.md
+└── module-name/
+    └── index.md              # Module content
+```
+
+- Content goes in `index.md` files using CommonMark markdown
+- Images go in the topic-level `images/` directory
+- Sample code and project files go in the topic-level `samples/` directory
+- Every sample project should include a README explaining how to build and run it
+- Reference images using relative paths: `![alt](images/filename.png)`
+
+---
+
+## Content Style Guide
+
+### Tone
+- Direct and practical — teach by showing, not lecturing
+- Assume intelligence, not prior knowledge
+- Use "you" not "the student" or "one"
+
+### Structure
+- Every page starts with frontmatter (`title` required)
+- Open with a short paragraph explaining what and why
+- Use code blocks liberally — real, runnable examples
+- End modules with exercises (drill, challenges, mini-project)
+- End with key takeaways and a "Next" link
+
+### Code
+- All code must be correct and runnable
+- Include comments only where the logic is not obvious
+- Show output where it helps understanding
+- For multi-language topics, show C, Python, Rust, C++, and Bash where applicable
+
+### Software Installation
+- When a module requires extra software, link to the official site and include
+  installation steps for Arch Linux (primary), Debian/Ubuntu, and Fedora
+- Use system package managers where possible
+- Note any version requirements
+
+### Images
+- Prefer ASCII diagrams for simple cases
+- Store image files in `topic/images/` with descriptive names
+- Reference using relative paths: `![description](images/filename.png)`
+- Always include `alt` text
+
+### Naming
+- Directories: `kebab-case` (e.g., `text-processing`, `pointers-and-memory`)
+- Files: `kebab-case.md` for content, descriptive names for images and samples
+- No spaces, no uppercase in file/directory names
+
+---
+
+## Contributing via Sourcehut (primary)
+
+The canonical repository is on
+[sr.ht](https://git.sr.ht/~gumxcc/ubergeek). Contributions are accepted via
+email patches.
+
+### Setup
+
+```bash
+# Clone the repo
+git clone https://git.sr.ht/~gumxcc/ubergeek
+cd ubergeek
+
+# Configure git send-email (one-time setup)
+git config sendemail.to ~gumxcc/ubergeek@lists.sr.ht
+git config format.subjectPrefix "PATCH ubergeek"
+```
+
+### Submitting a Patch
+
+```bash
+# Create a branch and make your changes
+git checkout -b fix-typo-shell-basics
+# ... edit files ...
+git add -A
+git commit -m "fix: correct permissions example in shell basics"
+
+# Send patch via email
+git send-email --to=~gumxcc/ubergeek@lists.sr.ht HEAD~1
+```
+
+For multi-commit changes:
+
+```bash
+git send-email --to=~gumxcc/ubergeek@lists.sr.ht origin/main..HEAD
+```
+
+### Discussion
+
+Use the mailing list for questions, suggestions, and reviews:
+`~gumxcc/ubergeek@lists.sr.ht`
+
+See [git-send-email.io](https://git-send-email.io) for a tutorial on setting
+up `git send-email`.
+
+---
+
+## Contributing via GitHub / GitLab (mirrors)
+
+Pull requests (GitHub) and merge requests (GitLab) are both accepted.
+
+```bash
+# Fork the repo on GitHub or GitLab, then clone your fork
+git clone https://github.com/gumxcc/ubergeek.git   # or gitlab.com
+cd ubergeek
+
+# Create a branch
+git checkout -b fix-typo-shell-basics
+
+# Make changes, commit, push
+git add -A
+git commit -m "fix: correct permissions example in shell basics"
+git push origin fix-typo-shell-basics
+
+# Open a pull/merge request from the web UI
+```
+
+### PR/MR Guidelines
+- Keep PRs focused — one fix or one module per PR
+- Write a clear description of what you changed and why
+- If adding a new module, open an issue first to discuss scope
+
+---
+
+## Sample Code Guidelines
+
+When adding to `samples/`:
+
+- **Must compile/run out of the box** — include a Makefile, requirements.txt,
+  Cargo.toml, or whatever the project needs
+- **Include a README.md** — what it does, how to build, how to run, expected output
+- **Keep it minimal** — demonstrate the concept, nothing more
+- **Pin dependencies** where practical — don't rely on "latest"
+- **Test on Linux** — that's the primary platform for this guide
+
+### KiCad / Hardware Projects
+
+- Include the full KiCad project directory (`.kicad_pro`, `.kicad_sch`, `.kicad_pcb`)
+- Add a README.md with a description and BOM
+- Export a schematic PDF and place it in `images/` for people without KiCad
+- Use KiCad's built-in libraries where possible
+
+---
+
+## Commit Messages
+
+```
+<type>: <short description>
+
+<optional body explaining why>
+```
+
+Types:
+- `content` — new or updated study material
+- `fix` — corrections to existing content
+- `exercises` — new or updated exercises
+- `samples` — new or updated sample code/projects
+- `images` — new or updated diagrams/images
+- `meta` — PROGRESS.md, CONTRIBUTING.md, index.md, study-plan.md
+- `infra` — CI, build scripts, tooling
+
+Examples:
+```
+content: add shell basics module for linux command line
+fix: correct voltage divider formula in electronics
+exercises: add pipeline challenges to text processing
+samples: add bare-metal blinky project for STM32F4
+```
+
+---
+
+## Review Process
+
+1. All contributions are reviewed before merging
+2. Content accuracy is the top priority
+3. Style and formatting can be fixed post-merge — don't let it block good content
+4. Disagreements are resolved by discussion, not authority
+
+---
+
+## License
+
+By contributing, you agree that your contributions will be licensed under
+CC BY-SA 4.0, the same license as the rest of the project. Code samples in
+`samples/` directories are additionally available under the MIT license.