Skip to content

Commit fa4f230

Browse files
hsluoyzhsluoyz
committed
fix: add CONTRIBUTING.md
1 parent 331ce13 commit fa4f230

1 file changed

Lines changed: 167 additions & 0 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# Contributing to OpenAgent
2+
3+
Thank you for your interest in contributing to OpenAgent! This document explains how to get involved.
4+
5+
## Code of Conduct
6+
7+
Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.
8+
9+
## Ways to Contribute
10+
11+
- **Bug reports** — open an issue with steps to reproduce, expected vs. actual behavior, and environment details
12+
- **Feature requests** — open an issue describing the use case and proposed solution
13+
- **Code contributions** — bug fixes, new features, documentation improvements
14+
- **New AI providers** — integrate a new model provider in `model/`
15+
- **Translations** — improve or add locales under `web/src/locales/`
16+
17+
## Development Setup
18+
19+
### Prerequisites
20+
21+
| Tool | Version |
22+
|------|---------|
23+
| Go | 1.23.6+ |
24+
| Node.js | 20+ |
25+
| Yarn | 1.x |
26+
| MySQL | 8.0+ (or MariaDB) |
27+
| Casdoor | latest (for auth) |
28+
29+
### 1. Clone and configure
30+
31+
```bash
32+
git clone https://github.com/the-open-agent/openagent.git
33+
cd openagent
34+
cp conf/app.conf.example conf/app.conf # edit DB and Casdoor settings
35+
```
36+
37+
Key fields in `conf/app.conf`:
38+
39+
```ini
40+
dataSourceName = root:password@tcp(localhost:3306)/openagent
41+
casdoorEndpoint = http://localhost:8000
42+
casdoorClientId = <your-client-id>
43+
casdoorClientSecret = <your-client-secret>
44+
casdoorOrganization = built-in
45+
casdoorApplication = app-openagent
46+
```
47+
48+
### 2. Start Casdoor (auth service)
49+
50+
```bash
51+
# Using Docker
52+
docker run -d -p 8000:8000 casbin/casdoor-all-in-one
53+
```
54+
55+
Create an application in Casdoor and copy the client ID/secret into `app.conf`.
56+
57+
### 3. Backend
58+
59+
```bash
60+
# Install dependencies and run
61+
go mod download
62+
go run main.go
63+
# Runs on http://localhost:14444 by default
64+
```
65+
66+
### 4. Frontend
67+
68+
```bash
69+
cd web
70+
yarn install
71+
yarn start # Dev server on http://localhost:3000 (proxies API to :14444)
72+
```
73+
74+
### 5. Docker (all-in-one, quickest start)
75+
76+
```bash
77+
docker-compose up
78+
# Opens on http://localhost:14444
79+
```
80+
81+
## Making Changes
82+
83+
1. **Fork** the repository and create a branch from `master`:
84+
85+
```bash
86+
git checkout -b feat/your-feature-name
87+
```
88+
89+
Use a semantic prefix — `feat/`, `fix/`, `docs/`, `chore/`, or `refactor/`.
90+
91+
2. Make your changes following the conventions below.
92+
93+
3. **Run tests and lint** before pushing:
94+
95+
```bash
96+
# Backend
97+
go test -v $(go list ./...) -tags skipCi
98+
golangci-lint run
99+
100+
# Frontend
101+
cd web && yarn lint && yarn test
102+
```
103+
104+
4. **Commit** with a semantic message:
105+
106+
```
107+
feat: add support for XYZ provider
108+
fix: resolve crash when uploading PDF
109+
docs: update deployment instructions
110+
```
111+
112+
5. **Open a pull request** against `master` with a clear description of what changed and why.
113+
114+
## Code Conventions
115+
116+
### Backend (Go)
117+
118+
- Beego MVC pattern: controllers handle HTTP, `object/` contains business logic
119+
- New AI model providers go in `model/` and must implement the provider interface
120+
- Routes are registered in `routers/router.go`
121+
- Formatting: `gofumpt` (enforced by golangci-lint)
122+
- Avoid duplicate i18n keys between frontend and backend
123+
124+
### Frontend (React)
125+
126+
- UI components use Ant Design v5
127+
- i18n strings must be added to **both** `web/src/locales/en/data.json` and `web/src/locales/zh/data.json`
128+
- API calls go through helper modules in `web/src/backend/`
129+
- State via React Context/Hooks — no Redux
130+
131+
## Adding a New AI Provider
132+
133+
1. Create `model/<provider>.go` implementing the provider interface (see `model/openai.go` for reference).
134+
2. Register the provider in `model/provider.go`.
135+
3. Add the provider name to the frontend select options and i18n strings.
136+
4. Add a test in `model/<provider>_test.go` if an API key can be mocked or injected via env.
137+
138+
## Adding Translations
139+
140+
1. Add new keys to `web/src/locales/en/data.json` (English, required).
141+
2. Add the same keys to `web/src/locales/zh/data.json` (Chinese).
142+
3. Additional locales in `web/src/locales/` are welcome — copy the `en/` folder structure.
143+
4. Run `cd web && yarn lint` to catch missing keys.
144+
145+
## CI/CD Expectations
146+
147+
Every pull request runs the following checks automatically:
148+
149+
| Check | Command |
150+
|-------|---------|
151+
| Go unit tests | `go test -v ./... -tags skipCi` |
152+
| Go build | `go build ./...` |
153+
| golangci-lint | `golangci-lint run` |
154+
| Frontend build | `yarn run build` |
155+
| Frontend lint | `yarn lint` |
156+
157+
All checks must pass before a PR can be merged.
158+
159+
## Reporting Security Vulnerabilities
160+
161+
Please **do not** open a public issue for security vulnerabilities. Report them privately via [GitHub Security Advisories](https://github.com/the-open-agent/openagent/security/advisories/new).
162+
163+
## Getting Help
164+
165+
- [GitHub Discussions](https://github.com/the-open-agent/openagent/discussions)
166+
- [Discord](https://discord.gg/5rPsrAzK7S)
167+
- [GitHub Issues](https://github.com/the-open-agent/openagent/issues)

0 commit comments

Comments
 (0)