Skip to content

fix: Add a contributor onboarding guide for new maintainers #341

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
HMS091 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

fix: Add a contributor onboarding guide for new maintainers #341

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
252 changes: 151 additions & 101 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
```
<type>(<scope>): <description>

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! 🚀