Contributing
Thank you for taking the time to look at this. Whether you are reporting a bug, suggesting an idea or just passing through, I appreciate it.
This is my shared contributing guide, kept in one place so I am not repeating myself across repositories. My work spans software, hardware, a mix of the two, writing, courses and this website. Most are personal projects I build for myself and am not actively taking contributions on; a few are more public and genuinely welcome them. This guide is the common ground for all of them. Where a repository works differently, it says so in its own notes; those take precedence over anything here.
What this covers
The same guide applies across everything I build, so the way in is consistent wherever you land:
Software and hardware. Web apps and tools, plus embedded firmware, PCBs and electronics. Many projects are a mix of the two.
Writing and courses. Notes, guides and course material, where clarity and accuracy matter as much as code.
Images and design. Diagrams, screenshots, schematics and other assets that make a project easier to follow.
This website. Anything you spot on isaacadjei.me itself, from a broken link to a typo.
You can browse the range on my projects page or across my repositories on GitHub.
Ways to help
Report a software bug. Open an issue on the repository and describe it plainly: what you did, what you expected and what happened instead. A small, clear example helps more than anything, even a link or a screenshot. For something on this website, tell me the page and your browser too. This is genuinely the most useful thing you can do, even if I do not get to it straight away.
Flag a hardware problem. If the project involves hardware, tell me your setup: the board or parts, how it is wired, the measurements you took and the versions or environment. A photo of the build often says more than a paragraph, so please include one where you can.
Improve the writing or a course. Notes, guides and lessons benefit from a second pair of eyes. Point out anything unclear, wrong or out of date, or suggest an example that would explain it better.
Design, images and media. A clearer diagram, a better screenshot, a tidier schematic or a fixed asset are all welcome. Tell me what it replaces and why it is better.
Suggest an idea or an improvement. Open an issue and explain the problem you are trying to solve, not only the solution you have in mind. I am more likely to act on the why than the what.
Fix a typo or small wording slip. These are always welcome. If it is trivial, feel free to open a pull request directly and skip the issue.
Ask a question.Use the repository's Discussions if it has them. Otherwise get in touch, see below.
Report a security issue.Please do not open a public issue for this. Follow the repository's own security policy if it has one, otherwise see my security policy.
Pull requests
Once we agree a change is worth doing:
- One change is one branch is one pull request. I keep unrelated work apart.
- Keep it small and focused. A tight pull request is read and merged far quicker than one that does five things at once.
- Link the issue it closes with Closes #123.
- Conventional commit prefixes in the present tense (a repository may override these): feat, fix, chore, ci, docs.
Using AI
You are welcome to use AI tools while you work. Two ground rules.
Write in your own voice. When you open an issue, leave a comment or describe a pull request, use your own words. I do not mind imperfect grammar; I mind not being able to tell what you actually mean. Pasted AI text tends to be long, vague and sure of itself while being wrong, which makes it much harder to help you.
Understand what you submit. Use AI to write code or to find your way around, but read it and make sense of it before it becomes a pull request. Own it as your work. A change that is clearly generated with no understanding behind it will probably be closed without a long discussion.
Patience appreciated
These are personal projects, so I am not always quick to respond and may not get to everything. A clear, well-described issue is the most likely to be picked up when I have the time. Thank you for your patience.
Getting in touch
Not everything fits an issue or a discussion. If something is unclear or more personal, email [email protected] or use my contact page. I will always try to help where I can.
Where this applies
This is the shared guide across my repositories and most of my projects, kept in the zaccesss/contribute repository. A repository with its own contributing notes takes precedence over this one. Thank you again for helping make my projects better.