From 315d5959b4798dcb0e4d8cb5d56466ff5d083425 Mon Sep 17 00:00:00 2001 From: Aryan Pandit Date: Mon, 9 Mar 2026 18:26:27 -0700 Subject: [PATCH] docs: update contributing file --- CONTRIBUTING.md | 290 +++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 263 insertions(+), 27 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 38c27b1..edd80ee 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,27 +1,263 @@ -# Contributing to CodeTrans - -Thank you for your interest in contributing to **CodeTrans — AI-Powered Code Translation** by Cloud2 Labs. - -## Scope of Contributions - -Appropriate contributions include: - -- Documentation improvements -- Bug fixes -- Reference architecture enhancements -- Additional LLM provider configurations -- Educational clarity and examples - -Major feature additions or architectural changes (e.g., new inference backends, -new supported languages, UI framework changes) require prior discussion with the -Cloud2 Labs maintainers. - -## Contribution Guidelines - -- Follow existing coding and documentation standards -- Avoid production-specific assumptions -- Do not introduce sensitive, proprietary, or regulated data into examples or tests -- Ensure any new environment variables are documented in `.env.example` and the README - -By submitting a contribution, you agree that your work may be used, modified, -and redistributed by Cloud2 Labs under the terms of the project license. +# Contributing to CodeTrans + +Thanks for your interest in contributing to CodeTrans. + +CodeTrans is an open-source code translation app built with a FastAPI backend, a React frontend, and a pluggable inference layer that supports OpenAI-compatible APIs and local Ollama models. We welcome improvements across the codebase, documentation, bug reports, design feedback, and workflow polish. + +Before you start, read the relevant section below. It helps keep contributions focused, reviewable, and aligned with the current project setup. + +--- + +## Quick Setup Checklist + +Before you dive in, make sure you have these installed: + +```bash +# Check Python (3.11+ recommended) +python --version + +# Check Node.js (18+ recommended) +node --version + +# Check npm +npm --version + +# Check Docker +docker --version +docker compose version + +# Check Git +git --version +``` + +New to contributing? + +1. Open an issue or pick an existing one to work on. +2. Sync your branch from `dev`. +3. Follow the local setup guide below. +4. Run the app locally and verify your change before opening a PR. + +## Table of contents + +- [How do I...?](#how-do-i) + - [Get help or ask a question?](#get-help-or-ask-a-question) + - [Report a bug?](#report-a-bug) + - [Suggest a new feature?](#suggest-a-new-feature) + - [Set up CodeTrans locally?](#set-up-codetrans-locally) + - [Start contributing code?](#start-contributing-code) + - [Improve the documentation?](#improve-the-documentation) + - [Submit a pull request?](#submit-a-pull-request) +- [Code guidelines](#code-guidelines) +- [Pull request checklist](#pull-request-checklist) +- [Branching model](#branching-model) +- [Thank you](#thank-you) + +--- + +## How do I... + +### Get help or ask a question? + +- Start with the main project docs in [`README.md`](./README.md), [`TROUBLESHOOTING.md`](./TROUBLESHOOTING.md), [`SECURITY.md`](./SECURITY.md), and [`.env.example`](./.env.example). +- If something is unclear, open a GitHub issue with your question and the context you already checked. + +### Report a bug? + +1. Search existing issues first. +2. If the bug is new, open a GitHub issue. +3. Include your environment, what happened, what you expected, and exact steps to reproduce. +4. Add screenshots, logs, request details, or response payloads if relevant. + +### Suggest a new feature? + +1. Open a GitHub issue describing the feature. +2. Explain the problem, who it helps, and how it fits CodeTrans. +3. If the change is large, get alignment in the issue before writing code. + +### Set up CodeTrans locally? + +#### Prerequisites + +- Python 3.11+ +- Node.js 18+ and npm +- Git +- Docker with Docker Compose v2 +- One inference option: + - An OpenAI-compatible API key, or + - Ollama installed locally on the host machine + +#### Option 1: Local development + +##### Step 1: Clone the repository + +```bash +git clone https://github.com/cld2labs/CodeTrans.git +cd CodeTrans +``` + +##### Step 2: Configure environment variables + +Create a root `.env` file from the example: + +```bash +cp .env.example .env +``` + +At minimum, set the provider values you plan to use. Example for a remote endpoint: + +```env +INFERENCE_PROVIDER=remote +INFERENCE_API_ENDPOINT=https://api.openai.com +INFERENCE_API_TOKEN=your_api_key_here +INFERENCE_MODEL_NAME=gpt-4o-mini +``` + +Example for local Ollama: + +```env +INFERENCE_PROVIDER=ollama +INFERENCE_API_ENDPOINT=http://localhost:11434 +INFERENCE_MODEL_NAME=codellama:7b +``` + +##### Step 3: Install backend dependencies + +```bash +cd api +python -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt +cd .. +``` + +##### Step 4: Install frontend dependencies + +```bash +cd ui +npm install +cd .. +``` + +##### Step 5: Start the backend + +```bash +cd api +source .venv/bin/activate +uvicorn server:app --reload --port 5001 +``` + +The backend runs at `http://localhost:5001`. + +##### Step 6: Start the frontend + +Open a second terminal: + +```bash +cd ui +npm run dev +``` + +The Vite dev server runs at `http://localhost:5173`. + +##### Step 7: Access the application + +- Frontend: `http://localhost:5173` +- Backend health check: `http://localhost:5001/health` +- API docs: `http://localhost:5001/docs` + +#### Option 2: Docker + +From the repository root: + +```bash +cp .env.example .env +docker compose up --build +``` + +This starts: + +- Frontend on `http://localhost:3000` +- Backend on `http://localhost:5001` + +#### Common troubleshooting + +- If ports `3000`, `5001`, or `5173` are already in use, stop the conflicting process before starting CodeTrans. +- If inference requests fail, confirm your `.env` values are correct for the selected provider. +- If you use Ollama with Docker, make sure Ollama is running on the host and reachable from the app. +- If Docker fails to build, rebuild with `docker compose up --build`. +- If Python packages fail to install, confirm you are using a supported Python version. + +### Start contributing code? + +1. Open or choose an issue. +2. Create a feature branch from `dev`. +3. Keep the change focused on a single problem. +4. Run the app locally and verify the affected workflow. +5. Update docs when behavior, setup, configuration, or architecture changes. +6. Open a pull request back to `dev`. + +### Improve the documentation? + +Documentation updates are welcome. Relevant files currently live in: + +- [`README.md`](./README.md) +- [`TROUBLESHOOTING.md`](./TROUBLESHOOTING.md) +- [`SECURITY.md`](./SECURITY.md) +- [`DISCLAIMER.md`](./DISCLAIMER.md) +- [`ui/src`](./ui/src) + +### Submit a pull request? + +Follow the checklist below before opening your PR. Your pull request should: + +- Stay focused on one issue or topic. +- Explain what changed and why. +- Include manual verification steps. +- Include screenshots or short recordings for UI changes. +- Reference the related GitHub issue when applicable. + +Note: pull requests should target the `dev` branch. + +--- + +## Code guidelines + +- Follow the existing project structure and patterns before introducing new abstractions. +- Keep frontend changes consistent with the React + Vite + Tailwind setup already in use. +- Keep backend changes consistent with the FastAPI service structure in [`api`](./api). +- Avoid unrelated refactors in the same pull request. +- Do not commit secrets, API keys, uploaded files, local `.env` files, or generated artifacts. +- Prefer clear, small commits and descriptive pull request summaries. +- Update documentation when contributor setup, behavior, environment variables, or API usage changes. + +--- + +## Pull request checklist + +Before submitting your pull request, confirm the following: + +- You tested the affected flow locally. +- The application still starts successfully in the environment you changed. +- You removed debug code, stray logs, and commented-out experiments. +- You documented any new setup steps, environment variables, or behavior changes. +- You kept the pull request scoped to one issue or topic. +- You added screenshots for UI changes when relevant. +- You did not commit secrets or local generated data. +- You are opening the pull request against `dev`. + +If one or more of these are missing, the pull request may be sent back for changes before review. + +--- + +## Branching model + +- Base new work from `dev`. +- Open pull requests against `dev`. +- Use descriptive branch names such as `fix/pdf-upload-validation` or `docs/update-contributing-guide`. +- Rebase or merge the latest `dev` before opening your PR if your branch has drifted. + +--- + +## Thank you + +Thanks for contributing to CodeTrans. Whether you're fixing a bug, improving the docs, or refining the product experience, your work helps make the project more useful and easier to maintain.