1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
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: ``
---
## 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: ``
- 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.
|
