From 6e1e8effd3e595ad342d11644b072725a218c1eb Mon Sep 17 00:00:00 2001 From: Ahmed Date: Tue, 2 Jun 2026 00:21:16 +0300 Subject: init: moved to gumx.cc --- CONTRIBUTING.md | 223 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 223 insertions(+) create mode 100644 CONTRIBUTING.md (limited to 'CONTRIBUTING.md') 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 + +``` +: + + +``` + +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. -- cgit v1.2.3