From eae6bc07a3a776c2cf6f4d718327589451f9e353 Mon Sep 17 00:00:00 2001 From: HMS091 Bot Date: Wed, 3 Jun 2026 18:11:12 +0000 Subject: [PATCH] fix: Add a contributor onboarding guide for new maintainers Closes #320 Bounty submission. --- CONTRIBUTING.md | 252 +++++++++++++++++++++++++++++------------------- 1 file changed, 151 insertions(+), 101 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 72b3510..ab66f1d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,154 +1,204 @@ -# Contributing to LocalMind ๐Ÿง  +# Contributing to LocalMind -Thank you for wanting to contribute! LocalMind is built by and for the community. -Every contribution โ€” big or small โ€” matters. ๐Ÿ’œ - ---- +First off, thank you for considering contributing to LocalMind! We welcome contributions from everyone, whether you're fixing a bug, adding a feature, improving documentation, or helping with testing. ## Table of Contents - [Code of Conduct](#code-of-conduct) -- [How to Contribute](#how-to-contribute) -- [Setting Up Locally](#setting-up-locally) -- [Making a Pull Request](#making-a-pull-request) -- [Issue Guidelines](#issue-guidelines) +- [Getting Started](#getting-started) + - [Prerequisites](#prerequisites) + - [Setting Up the Development Environment](#setting-up-the-development-environment) + - [Running the Project Locally](#running-the-project-locally) +- [Development Workflow](#development-workflow) + - [Branching Strategy](#branching-strategy) + - [Commit Messages](#commit-messages) + - [Pull Requests](#pull-requests) - [Coding Standards](#coding-standards) - ---- + - [Backend (Python)](#backend-python) + - [Frontend (JavaScript/React)](#frontend-javascriptreact) +- [Testing](#testing) +- [Documentation](#documentation) +- [Issue Tracker](#issue-tracker) +- [Getting Help](#getting-help) ## Code of Conduct -Please read [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Be kind. Be respectful. +This project and everyone participating in it is governed by the [LocalMind Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers. ---- +## Getting Started -## How to Contribute +### Prerequisites -### Beginners โ€” start here! -Look for issues labeled [`good-first-issue`](https://github.com/yourusername/localmind/issues?q=label%3Agood-first-issue). -These are small, well-defined tasks perfect for your first PR. +Before you begin, ensure you have the following installed: -Types of contributions: -| Type | Examples | -|------|---------| -| ๐Ÿ› Bug Fix | Fix a broken endpoint, UI glitch | -| โœจ Feature | Add new model support, new file type | -| ๐ŸŒ Translation | Translate UI to Hindi, Tamil, Telugu | -| ๐Ÿ“ Docs | Improve README, add tutorials | -| ๐Ÿงช Tests | Write pytest tests, add test cases | -| ๐ŸŽจ UI/UX | Improve the React frontend | +- **Git** โ€“ for version control +- **Docker** and **Docker Compose** โ€“ for running the project locally (recommended) +- **Node.js** (v18 or later) and **npm** โ€“ if running the frontend outside Docker +- **Python** (3.10 or later) and **pip** โ€“ if running the backend outside Docker +- **Ollama** โ€“ for local LLM inference (optional but recommended for full functionality) ---- +### Setting Up the Development Environment + +1. **Fork the repository** on GitHub. +2. **Clone your fork** locally: + + ```bash + git clone https://github.com/your-username/localmind.git + cd localmind + ``` + +3. **Add the upstream remote** to keep your fork in sync: + + ```bash + git remote add upstream https://github.com/imDarshanGK/localmind.git + ``` + +4. **Create a new branch** for your work: + + ```bash + git checkout -b feature/your-feature-name + ``` + +### Running the Project Locally -## Setting Up Locally +#### Using Docker (Recommended) + +The easiest way to run the entire stack is with Docker Compose: ```bash -# 1. Fork the repo on GitHub, then clone your fork -git clone https://github.com/YOUR_USERNAME/localmind.git -cd localmind +# Copy environment file +cp .env.example .env -# 2. Create a virtual environment -python -m venv venv -source venv/bin/activate # Windows: venv\Scripts\activate +# Start all services +docker-compose up --build +``` -# 3. Install backend dependencies +This will start: +- Backend API at `http://localhost:8000` +- Frontend at `http://localhost:5173` + +#### Without Docker + +**Backend:** + +```bash cd backend +python -m venv venv +source venv/bin/activate # On Windows: venv\Scripts\activate pip install -r requirements.txt -cd .. +python app.py +``` -# 4. Install frontend dependencies +**Frontend:** + +```bash cd frontend npm install -cd .. +npm run dev +``` -# 5. Copy environment variables -cp .env.example .env +## Development Workflow -# 6. Pull an AI model -ollama pull llama3 +### Branching Strategy -# 7. Start backend -cd backend && uvicorn app:app --reload --port 8000 +We follow a simple branching model: -# 8. Start frontend (new terminal) -cd frontend && npm run dev -``` +- `main` โ€“ stable, production-ready code +- `develop` โ€“ integration branch for features +- `feature/*` โ€“ for new features +- `fix/*` โ€“ for bug fixes +- `docs/*` โ€“ for documentation changes ---- +Always branch off from `main` (or `develop` if it exists) and create a pull request back to the same branch. -## Making a Pull Request +### Commit Messages -1. **Create a branch** from `main`: - ```bash - git checkout -b feature/your-feature-name - # or - git checkout -b fix/bug-description - ``` +We encourage clear, descriptive commit messages. Follow the [Conventional Commits](https://www.conventionalcommits.org/) format: -2. **Make your changes** โ€” keep them focused on one thing. +``` +(): -3. **Write tests** for your changes (if applicable). +[optional body] +``` -4. **Commit** with a clear message: - ```bash - git commit -m "feat: add Gemma model support" - git commit -m "fix: handle empty PDF upload" - git commit -m "docs: improve quick start guide" - ``` - We follow [Conventional Commits](https://www.conventionalcommits.org/). +Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore` -5. **Push and open a PR**: - ```bash - git push origin feature/your-feature-name - ``` - Open a PR on GitHub. Fill in the PR template. +Examples: +- `feat(chat): add markdown rendering to messages` +- `fix(api): handle empty session list gracefully` +- `docs(readme): update installation instructions` -6. **Wait for review** โ€” we aim to review within 48 hours! +### Pull Requests ---- +1. **Keep PRs small and focused** โ€“ one feature or fix per PR. +2. **Write a clear description** explaining what the PR does and why. +3. **Reference related issues** using `Closes #123` or `Fixes #123`. +4. **Ensure all checks pass** โ€“ CI will run tests and linting. +5. **Request a review** from at least one maintainer. -## Issue Guidelines +## Coding Standards -When opening a bug report: -- Describe what you expected vs what happened -- Include steps to reproduce -- Include your OS, Python version, and Ollama version +### Backend (Python) -When requesting a feature: -- Explain the use case -- Why does it belong in LocalMind? +- Follow [PEP 8](https://peps.python.org/pep-0008/) style guide. +- Use type hints for function signatures. +- Write docstrings for public functions and classes. +- Keep functions small and focused (single responsibility). +- Use meaningful variable and function names. ---- +### Frontend (JavaScript/React) -## Coding Standards +- Use functional components with hooks (no class components). +- Follow the existing project structure and naming conventions. +- Use Tailwind CSS for styling (avoid inline styles). +- Keep components small and reusable. +- Use meaningful component and prop names. -**Python (backend)** -- Follow PEP 8 -- Use type hints -- Write docstrings for functions -- Run `black .` before committing +## Testing -**JavaScript/React (frontend)** -- Use functional components + hooks -- Keep components small and focused -- Follow the existing file structure +We value tests to ensure reliability and prevent regressions. -**Tests** -```bash -# Run backend tests -cd backend && pytest +- **Backend tests** are located in `backend/tests/` and use pytest. +- **Frontend tests** (if any) should be placed alongside components. -# Run with coverage -pytest --cov=. --cov-report=term +To run backend tests: + +```bash +cd backend +pytest ``` ---- +When adding new functionality, please include corresponding tests. If fixing a bug, consider adding a test that reproduces the issue. + +## Documentation + +Good documentation helps everyone understand and use the project. + +- Update `README.md` if you change installation steps or add major features. +- Update `ROADMAP.md` if you add or remove planned features. +- Document new API endpoints in the backend code (docstrings). +- If you add a new environment variable, update `.env.example`. + +## Issue Tracker + +We use GitHub Issues to track bugs, feature requests, and tasks. + +- **Bug reports** โ€“ use the bug report template and include steps to reproduce. +- **Feature requests** โ€“ use the feature request template and describe the use case. +- **Questions** โ€“ feel free to open an issue with the `question` label. + +If you're new to the project, look for issues labeled `good first issue` or `help wanted`. + +## Getting Help + +If you get stuck or have questions: -## Need Help? +- Check the existing [issues](https://github.com/imDarshanGK/localmind/issues) and [discussions](https://github.com/imDarshanGK/localmind/discussions). +- Ask in the issue or PR you're working on. +- Reach out to maintainers via GitHub. -Open a [Discussion](https://github.com/yourusername/localmind/discussions) or comment on the issue. -We're here to help! ๐Ÿ™Œ +We're here to help and appreciate your contribution! --- -Made with โค๏ธ for Social Summer of Code 2026 +Thank you for contributing to LocalMind! ๐Ÿš€