---
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.