First off, thank you for considering a contribution! 🎉 This project exists to make machine learning approachable for everyone, and contributions of all kinds — code, content, docs, design, and bug reports — are welcome and appreciated.
By participating, you agree to abide by our Code of Conduct.
- 🌐 Live site: https://machinelearning101.com
- 🐛 Report a bug
- 💡 Request a feature
- 🙋 Good first issues
- 🤝 Help wanted
You don't need to be an ML expert or a seasoned developer. Some of the most valuable contributions are:
| Type | Examples |
|---|---|
| 🐛 Bug fixes | Broken visualizations, wrong math, mobile layout issues |
| ✨ New modules | Add an algorithm, dataset, or interactive demo |
| 📚 Documentation | Fix typos, clarify explanations, improve the guides in docs/ |
| 🎨 Design & UX | Accessibility, responsive layout, clearer controls |
| ⚡ Performance | Bundle size, rendering, Web Worker offloading |
| 🧪 Tests | Increase coverage in tests/ |
| 🌍 Localization | Help translate the learning content |
Not sure where to start? Browse issues labeled
good first issue
or open a discussion/question
and we'll help you find something.
- Node.js 22 or higher (see
.nvmrc) — we recommend nvm:nvm use - npm 10 or higher
- Git
- Basic familiarity with Vue 3, TypeScript, and machine learning concepts is helpful but not required for docs/design work.
-
Fork the repository on GitHub (use the Fork button in the top-right).
-
Clone your fork and enter the directory:
git clone https://github.com/YOUR_USERNAME/machinelearning101.git cd machinelearning101 -
Add the upstream remote so you can stay in sync:
git remote add upstream https://github.com/marvelefe/machinelearning101.git
-
Install dependencies:
npm install
-
Start the dev server:
npm run dev
-
Verify by opening
http://localhost:3000.
Always branch off an up-to-date main:
git checkout main
git pull upstream main
git checkout -b feat/your-feature-name
# or
git checkout -b fix/short-bug-description
# or
git checkout -b docs/what-you-are-documentingBranch prefix convention: feat/, fix/, docs/, chore/, refactor/.
Please follow the project's coding standards (see AGENTS.md):
- TypeScript everywhere; no implicit
any, and type your public APIs. - Vue 3 Composition API with
<script setup>. - Keep functions small and single-purpose; prefer explicit over implicit.
- Follow the existing file/folder structure and naming conventions.
- Delete dead code — don't comment it out.
- Add JSDoc comments for public APIs.
- Ensure UI is keyboard accessible and responsive (desktop, tablet, mobile).
Run these before pushing — CI runs the same commands:
npm run test # Unit tests (Vitest)
npm run type-check # TypeScript type checking
npm run build # Must succeed with no errorsAdd or update tests for any new logic. One test file per module
(tests/<module>.test.ts).
We follow Conventional Commits:
git add .
git commit -m "feat: add k-nearest neighbors module"
git commit -m "fix: correct gradient descent step size"
git commit -m "docs: clarify feature scaling explanation"Use the imperative mood and keep commits atomic — one logical change per commit.
git push origin feat/your-feature-nameThen open a Pull Request against main. The
PR template will guide you. Link the issue
your PR addresses (e.g. Closes #123).
Before requesting review, make sure:
- The change is focused and does one thing
-
npm run testpasses -
npm run type-checkpasses -
npm run buildsucceeds - New/updated logic has tests
- Public APIs are typed and documented
- UI changes are responsive and keyboard accessible
- Relevant documentation is updated
- Commits follow Conventional Commits
- Branch is up to date with
main
Modules are the heart of this project. Each module lives under
content/modules/<domain>/<module>/ and contains three files:
config.json— metadata, parameters, datasets, visualizationscontent.md— the learning contentquiz.json— quiz questions and answers
Plus an algorithm implementation under algorithms/ that extends
BaseAlgorithm (types/algorithm.ts) and implements fit(), predict(),
getVisualizationData(), and getMetrics().
For a full walkthrough, see the Module Creation Guide.
Use the issue templates — they help us help you:
For security vulnerabilities, please do not open a public issue — follow our Security Policy instead.
| Document | Description |
|---|---|
| Developer Guide | Development setup and workflow |
| Module Creation Guide | Add a new learning module |
| State Management | How Pinia stores are organized |
| User Guide | End-user documentation |
| Deployment Guide | Deployment instructions |
| Worker README | Optional auth backend |
All contributors are valued. Meaningful contributions will be listed in release notes. Thank you for making Machine Learning 101 better! 🚀