Skip to content

Commit fd24e6c

Browse files
geethac2lgeethac2l
authored
Merge pull request #3 from cld2labs/docs/readme-update
docs: update contributing file
2 parents 308b0cf + 315d595 commit fd24e6c

File tree

1 file changed

+263
-27
lines changed

1 file changed

+263
-27
lines changed

‎CONTRIBUTING.md‎

Lines changed: 263 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,263 @@
1-
# Contributing to CodeTrans
2-
3-
Thank you for your interest in contributing to **CodeTrans — AI-Powered Code Translation** by Cloud2 Labs.
4-
5-
## Scope of Contributions
6-
7-
Appropriate contributions include:
8-
9-
- Documentation improvements
10-
- Bug fixes
11-
- Reference architecture enhancements
12-
- Additional LLM provider configurations
13-
- Educational clarity and examples
14-
15-
Major feature additions or architectural changes (e.g., new inference backends,
16-
new supported languages, UI framework changes) require prior discussion with the
17-
Cloud2 Labs maintainers.
18-
19-
## Contribution Guidelines
20-
21-
- Follow existing coding and documentation standards
22-
- Avoid production-specific assumptions
23-
- Do not introduce sensitive, proprietary, or regulated data into examples or tests
24-
- Ensure any new environment variables are documented in `.env.example` and the README
25-
26-
By submitting a contribution, you agree that your work may be used, modified,
27-
and redistributed by Cloud2 Labs under the terms of the project license.
1+
# Contributing to CodeTrans
2+
3+
Thanks for your interest in contributing to CodeTrans.
4+
5+
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.
6+
7+
Before you start, read the relevant section below. It helps keep contributions focused, reviewable, and aligned with the current project setup.
8+
9+
---
10+
11+
## Quick Setup Checklist
12+
13+
Before you dive in, make sure you have these installed:
14+
15+
```bash
16+
# Check Python (3.11+ recommended)
17+
python --version
18+
19+
# Check Node.js (18+ recommended)
20+
node --version
21+
22+
# Check npm
23+
npm --version
24+
25+
# Check Docker
26+
docker --version
27+
docker compose version
28+
29+
# Check Git
30+
git --version
31+
```
32+
33+
New to contributing?
34+
35+
1. Open an issue or pick an existing one to work on.
36+
2. Sync your branch from `dev`.
37+
3. Follow the local setup guide below.
38+
4. Run the app locally and verify your change before opening a PR.
39+
40+
## Table of contents
41+
42+
- [How do I...?](#how-do-i)
43+
- [Get help or ask a question?](#get-help-or-ask-a-question)
44+
- [Report a bug?](#report-a-bug)
45+
- [Suggest a new feature?](#suggest-a-new-feature)
46+
- [Set up CodeTrans locally?](#set-up-codetrans-locally)
47+
- [Start contributing code?](#start-contributing-code)
48+
- [Improve the documentation?](#improve-the-documentation)
49+
- [Submit a pull request?](#submit-a-pull-request)
50+
- [Code guidelines](#code-guidelines)
51+
- [Pull request checklist](#pull-request-checklist)
52+
- [Branching model](#branching-model)
53+
- [Thank you](#thank-you)
54+
55+
---
56+
57+
## How do I...
58+
59+
### Get help or ask a question?
60+
61+
- Start with the main project docs in [`README.md`](./README.md), [`TROUBLESHOOTING.md`](./TROUBLESHOOTING.md), [`SECURITY.md`](./SECURITY.md), and [`.env.example`](./.env.example).
62+
- If something is unclear, open a GitHub issue with your question and the context you already checked.
63+
64+
### Report a bug?
65+
66+
1. Search existing issues first.
67+
2. If the bug is new, open a GitHub issue.
68+
3. Include your environment, what happened, what you expected, and exact steps to reproduce.
69+
4. Add screenshots, logs, request details, or response payloads if relevant.
70+
71+
### Suggest a new feature?
72+
73+
1. Open a GitHub issue describing the feature.
74+
2. Explain the problem, who it helps, and how it fits CodeTrans.
75+
3. If the change is large, get alignment in the issue before writing code.
76+
77+
### Set up CodeTrans locally?
78+
79+
#### Prerequisites
80+
81+
- Python 3.11+
82+
- Node.js 18+ and npm
83+
- Git
84+
- Docker with Docker Compose v2
85+
- One inference option:
86+
- An OpenAI-compatible API key, or
87+
- Ollama installed locally on the host machine
88+
89+
#### Option 1: Local development
90+
91+
##### Step 1: Clone the repository
92+
93+
```bash
94+
git clone https://github.com/cld2labs/CodeTrans.git
95+
cd CodeTrans
96+
```
97+
98+
##### Step 2: Configure environment variables
99+
100+
Create a root `.env` file from the example:
101+
102+
```bash
103+
cp .env.example .env
104+
```
105+
106+
At minimum, set the provider values you plan to use. Example for a remote endpoint:
107+
108+
```env
109+
INFERENCE_PROVIDER=remote
110+
INFERENCE_API_ENDPOINT=https://api.openai.com
111+
INFERENCE_API_TOKEN=your_api_key_here
112+
INFERENCE_MODEL_NAME=gpt-4o-mini
113+
```
114+
115+
Example for local Ollama:
116+
117+
```env
118+
INFERENCE_PROVIDER=ollama
119+
INFERENCE_API_ENDPOINT=http://localhost:11434
120+
INFERENCE_MODEL_NAME=codellama:7b
121+
```
122+
123+
##### Step 3: Install backend dependencies
124+
125+
```bash
126+
cd api
127+
python -m venv .venv
128+
source .venv/bin/activate
129+
pip install -r requirements.txt
130+
cd ..
131+
```
132+
133+
##### Step 4: Install frontend dependencies
134+
135+
```bash
136+
cd ui
137+
npm install
138+
cd ..
139+
```
140+
141+
##### Step 5: Start the backend
142+
143+
```bash
144+
cd api
145+
source .venv/bin/activate
146+
uvicorn server:app --reload --port 5001
147+
```
148+
149+
The backend runs at `http://localhost:5001`.
150+
151+
##### Step 6: Start the frontend
152+
153+
Open a second terminal:
154+
155+
```bash
156+
cd ui
157+
npm run dev
158+
```
159+
160+
The Vite dev server runs at `http://localhost:5173`.
161+
162+
##### Step 7: Access the application
163+
164+
- Frontend: `http://localhost:5173`
165+
- Backend health check: `http://localhost:5001/health`
166+
- API docs: `http://localhost:5001/docs`
167+
168+
#### Option 2: Docker
169+
170+
From the repository root:
171+
172+
```bash
173+
cp .env.example .env
174+
docker compose up --build
175+
```
176+
177+
This starts:
178+
179+
- Frontend on `http://localhost:3000`
180+
- Backend on `http://localhost:5001`
181+
182+
#### Common troubleshooting
183+
184+
- If ports `3000`, `5001`, or `5173` are already in use, stop the conflicting process before starting CodeTrans.
185+
- If inference requests fail, confirm your `.env` values are correct for the selected provider.
186+
- If you use Ollama with Docker, make sure Ollama is running on the host and reachable from the app.
187+
- If Docker fails to build, rebuild with `docker compose up --build`.
188+
- If Python packages fail to install, confirm you are using a supported Python version.
189+
190+
### Start contributing code?
191+
192+
1. Open or choose an issue.
193+
2. Create a feature branch from `dev`.
194+
3. Keep the change focused on a single problem.
195+
4. Run the app locally and verify the affected workflow.
196+
5. Update docs when behavior, setup, configuration, or architecture changes.
197+
6. Open a pull request back to `dev`.
198+
199+
### Improve the documentation?
200+
201+
Documentation updates are welcome. Relevant files currently live in:
202+
203+
- [`README.md`](./README.md)
204+
- [`TROUBLESHOOTING.md`](./TROUBLESHOOTING.md)
205+
- [`SECURITY.md`](./SECURITY.md)
206+
- [`DISCLAIMER.md`](./DISCLAIMER.md)
207+
- [`ui/src`](./ui/src)
208+
209+
### Submit a pull request?
210+
211+
Follow the checklist below before opening your PR. Your pull request should:
212+
213+
- Stay focused on one issue or topic.
214+
- Explain what changed and why.
215+
- Include manual verification steps.
216+
- Include screenshots or short recordings for UI changes.
217+
- Reference the related GitHub issue when applicable.
218+
219+
Note: pull requests should target the `dev` branch.
220+
221+
---
222+
223+
## Code guidelines
224+
225+
- Follow the existing project structure and patterns before introducing new abstractions.
226+
- Keep frontend changes consistent with the React + Vite + Tailwind setup already in use.
227+
- Keep backend changes consistent with the FastAPI service structure in [`api`](./api).
228+
- Avoid unrelated refactors in the same pull request.
229+
- Do not commit secrets, API keys, uploaded files, local `.env` files, or generated artifacts.
230+
- Prefer clear, small commits and descriptive pull request summaries.
231+
- Update documentation when contributor setup, behavior, environment variables, or API usage changes.
232+
233+
---
234+
235+
## Pull request checklist
236+
237+
Before submitting your pull request, confirm the following:
238+
239+
- You tested the affected flow locally.
240+
- The application still starts successfully in the environment you changed.
241+
- You removed debug code, stray logs, and commented-out experiments.
242+
- You documented any new setup steps, environment variables, or behavior changes.
243+
- You kept the pull request scoped to one issue or topic.
244+
- You added screenshots for UI changes when relevant.
245+
- You did not commit secrets or local generated data.
246+
- You are opening the pull request against `dev`.
247+
248+
If one or more of these are missing, the pull request may be sent back for changes before review.
249+
250+
---
251+
252+
## Branching model
253+
254+
- Base new work from `dev`.
255+
- Open pull requests against `dev`.
256+
- Use descriptive branch names such as `fix/pdf-upload-validation` or `docs/update-contributing-guide`.
257+
- Rebase or merge the latest `dev` before opening your PR if your branch has drifted.
258+
259+
---
260+
261+
## Thank you
262+
263+
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.

0 commit comments

Comments
 (0)