Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
331 lines (228 loc) · 9.59 KB

CONTRIBUTING.md

File metadata and controls

331 lines (228 loc) · 9.59 KB

🤝 Contributing to LeetLog AI

First off — thank you! Whether it's your first open-source contribution or your hundredth, we're glad you're here. LeetLog AI is part of GSSoC 2025 and welcomes developers of all skill levels.

📋 Table of Contents

🙌 Code of Conduct

By participating in this project, you agree to be kind and constructive. Harassment, discrimination, or disrespectful behavior of any kind will not be tolerated. Let's keep this a welcoming space for everyone.

💡 How Can I Contribute?

Not sure where to start? Here are some great entry points:

Type What to do
🐛 Fix a bug Check Issues for open bugs
✨ Add a feature Look for issues labeled enhancement or good first issue
📖 Improve docs Fix typos, add examples, clarify the README or CONTRIBUTING guide
🧪 Write tests Help build a test suite for the backend API endpoints
🎨 Improve the UI Polish the Chrome extension popup design
🌐 Add platform support Extend devto.py to support Hashnode, Medium, etc.

💬 Always comment on an issue before starting work, so maintainers can assign it to you and avoid duplicate effort.

🔄 Contribution Workflow (Step-by-Step)

Step 1 — Find or Create an Issue

  • Browse open issues
  • If your idea doesn't have an issue yet, create one describing the problem or feature
  • Wait for a maintainer to assign the issue to you before starting work

Step 2 — Fork & Clone

Click Fork on the top-right of the GitHub repo page, then clone your fork:

git clone https://github.com/<your-username>/LeetcodeAI.git
cd LeetcodeAI

Add the original repo as upstream so you can stay in sync:

git remote add upstream https://github.com/vanshaggarwal27/LeetcodeAI.git

Step 3 — Create a Branch

Never work directly on main. Create a dedicated branch for your change:

# For a new feature:
git checkout -b feat/add-hashnode-support

# For a bug fix:
git checkout -b fix/devto-retry-logic

# For documentation:
git checkout -b docs/improve-contributing-guide

Branch names should be lowercase, hyphen-separated, and descriptive.

Step 4 — Set Up the Backend

cd backend

# Create and activate a virtual environment
python -m venv venv

# Windows
venv\Scripts\activate

# macOS / Linux
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Step 5 — Set Up Environment Variables

Create a .env file inside the backend/ directory:

# backend/.env
GEMINI_API_KEY=your_google_gemini_key_here
DEVTO_API_KEY=your_devto_api_key_here
HASHNODE_TOKEN=your_hashnode_token_here
HASHNODE_PUBLICATION_ID=your_hashnode_publication_id_here
MEDIUM_TOKEN=your_medium_integration_token_here
MEDIUM_USER_ID=your_medium_user_id_here
BLOG_WEBHOOK_URL=https://your-blog.example.com/api/publish
MONGODB_URI=your_mongodb_connection_string
MongoDB is required for the project to run.

You can either:

1. Use MongoDB Atlas (cloud)
2. Run locally using Docker:

docker run -d -p 27017:27017 --name mongodb mongo

Where to get your keys:

  • Gemini API Key → Google AI Studio
  • Dev.to API Key → Dev.to Settings → Extensions
  • Hashnode → create a developer token and copy the publication ID for the blog you want to publish to
  • Medium → create an integration token and set the target Medium user ID
  • Personal blog webhook → expose an endpoint that accepts title, body_markdown, tags, published, and source

⚠️ Never commit your .env file. It is already in .gitignore.

Step 6 — Run the Server Locally

# From inside the backend/ directory (with venv activated)
python main.py

You should see:

INFO:     Uvicorn running on http://0.0.0.0:10000 (Press CTRL+C to quit)

You can verify it's live by visiting: http://localhost:10000

Step 7 — Load the Chrome Extension

To test the extension against your local server:

  1. Open Chrome and go to chrome://extensions/
  2. Enable Developer mode (toggle in the top-right corner)
  3. Click "Load unpacked"
  4. Select the extension/ folder from the cloned repo

The extension in background.js points to the deployed Render URL by default. For local testing, temporarily change API_BASE_URL in background.js

const API_BASE_URL = "http://localhost:10000";

Step 8 — Make Your Changes

Write your code, fix the bug, or update the docs. Keep these things in mind:

  • Follow the Coding Standards below
  • Make sure the backend still starts without errors after your changes
  • Test your changes end-to-end if possible (open a LeetCode problem, click the extension)

Step 9 — Commit with a Good Message

Use the Conventional Commits format:

git add .
git commit -m "feat: add Hashnode publishing support"
Prefix When to use
feat: A new feature
fix: A bug fix
docs: Documentation only changes
refactor: Code cleanup without feature/fix
chore: Dependency updates, config changes
test: Adding or updating tests

Step 10 — Push & Open a Pull Request

First, sync with the latest main to avoid merge conflicts:

git fetch upstream
git rebase upstream/main

Then push your branch and open a PR:

git push origin feat/your-branch-name

Go to your fork on GitHub — you'll see a "Compare & pull request" button. Click it and fill in the PR template:

  • Title: Short and descriptive (e.g., feat: add Hashnode publishing)
  • Description:
    • What does this PR do?
    • Which issue does it close? (use Closes #<issue-number>)
    • How can reviewers test it?
  • Screenshots: Include before/after screenshots for any UI changes

A maintainer will review your PR within a few days. Be ready to address feedback — it's a normal part of the process! 🙂

🎨 Coding Standards

Python (Backend)

  • Follow PEP 8 style guidelines
  • Use snake_case for all variables and functions
  • Add a docstring to every new function explaining what it does
  • Keep each function focused on a single responsibility
  • Handle exceptions explicitly — avoid bare except: clauses

JavaScript (Extension)

  • Use camelCase for variables and function names
  • Prefer async/await over .then() chains for readability
  • Remove console.log debug statements before submitting a PR
  • Keep logic in background.js (networking) separate from popup.js (UI)

General Rules

  • ✅ One feature or fix per PR
  • ✅ No .env files or API keys in any commit — ever
  • ✅ Update the README.md if your change affects setup or usage
  • ✅ Keep diffs small and focused — easier to review, faster to merge

🐛 Reporting Bugs

Found something broken? Please open an issue and include:

  • Description — What is the bug?
  • Steps to Reproduce — Exact steps to trigger it
  • Expected Behavior — What should happen?
  • Actual Behavior — What actually happens?
  • Environment — OS, Chrome version, Python version
  • Logs / Screenshots — Any error messages from the console or terminal

Thank you for being part of LeetLog AI! Every contribution — big or small — matters. 🚀

Running Tests Locally

Prerequisites

  • Python 3.10+
  • All dependencies installed

Setup

cd backend pip install -r requirements.txt

Run the full test suite

make test

Or directly:

cd backend && pytest -v

Run the linter

make lint

Run the formatter

make format

Writing New Tests

Tests live in backend/tests/. Each file maps to a module:

  • test_routes.py API route integration tests
  • test_ai.py blog generation service tests
  • test_devto.py Dev.to publishing service tests

When adding a new external API integration, add a mock fixture for it in backend/tests/conftest.py before writing tests. Never make real API calls in tests.

Mock Fixtures Available

Fixture What it mocks
mock_generate_blog generate_blog() return value
mock_post_to_platform post_to_platform() return value
mock_gemini_client Gemini genai model directly
mock_devto_request requests.post to Dev.to
mock_db async MongoDB collection

All fixtures are in backend/tests/conftest.py.