contributing to ubergeek

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. Contributions are accepted via email patches.

Setup

# 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

# 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:

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 for a tutorial on setting up git send-email.

Contributing via GitHub / GitLab (mirrors)

Pull requests (GitHub) and merge requests (GitLab) are both accepted.

# 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

All contributions are reviewed before merging
Content accuracy is the top priority
Style and formatting can be fixed post-merge — don't let it block good content
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.