@@ -16,7 +16,7 @@ Thank you for your interest in contributing to OpenSandbox! This guide will help
1616
1717## Code of Conduct
1818
19- OpenSandbox adheres to a [ Code of Conduct] ( ../ CODE_OF_CONDUCT.md) that we expect all contributors to follow. Please read it before contributing to ensure a welcoming and inclusive environment for everyone.
19+ OpenSandbox adheres to a [ Code of Conduct] ( CODE_OF_CONDUCT.md ) that we expect all contributors to follow. Please read it before contributing to ensure a welcoming and inclusive environment for everyone.
2020
2121## Getting Started
2222
@@ -37,7 +37,7 @@ There are many ways to contribute to OpenSandbox:
37371 . ** Search Existing Issues** : Check if your bug report or feature request already exists
38382 . ** Check Roadmap** : Review the project roadmap to see if your idea aligns with project goals
39393 . ** Discuss Major Changes** : For significant changes, open an issue first or submit an [ OSEP] ( oseps/README.md ) to discuss your approach
40- 4 . ** Review Architecture** : Read [ docs/architecture.md] ( architecture.md ) to understand the system design
40+ 4 . ** Review Architecture** : Read [ docs/architecture.md] ( docs/ architecture.md) to understand the system design
4141
4242## Development Environment Setup
4343
@@ -46,16 +46,19 @@ There are many ways to contribute to OpenSandbox:
4646Different components have different requirements:
4747
4848#### For Server (Python)
49+
4950- ** Python 3.10+**
5051- ** uv** - Python package manager ([ installation guide] ( https://github.com/astral-sh/uv ) )
5152- ** Docker** - For running sandboxes locally
5253
5354#### For execd (Go)
55+
5456- ** Go 1.24+**
5557- ** Make** - Build automation (optional)
5658- ** Docker** - For building container images
5759
5860#### For SDKs
61+
5962- ** Python SDK** : Python 3.10+, uv
6063- ** Java/Kotlin SDK** : JDK 17+, Gradle
6164
@@ -81,7 +84,7 @@ nano ~/.sandbox.toml
8184uv run python -m src.main
8285```
8386
84- See [ server/DEVELOPMENT.md] ( ../ server/DEVELOPMENT.md) for detailed server development guide.
87+ See [ server/DEVELOPMENT.md] ( server/DEVELOPMENT.md ) for detailed server development guide.
8588
8689#### execd Development
8790
@@ -99,18 +102,20 @@ go build -o bin/execd .
99102./bin/execd --jupyter-host=http://localhost:8888 --port=44772
100103```
101104
102- See [ components/execd/DEVELOPMENT.md] ( ../ components/execd/DEVELOPMENT.md) for detailed execd development guide.
105+ See [ components/execd/DEVELOPMENT.md] ( components/execd/DEVELOPMENT.md ) for detailed execd development guide.
103106
104107#### SDK Development
105108
106109** Python SDK:**
110+
107111``` bash
108112cd sdks/sandbox/python
109113uv sync
110114uv run pytest
111115```
112116
113117** Java/Kotlin SDK:**
118+
114119``` bash
115120cd sdks/sandbox/kotlin
116121./gradlew build
@@ -190,6 +195,7 @@ We follow [Conventional Commits](https://www.conventionalcommits.org/) specifica
190195```
191196
192197** Types:**
198+
193199- ` feat ` : New feature
194200- ` fix ` : Bug fix
195201- ` docs ` : Documentation changes
@@ -201,6 +207,7 @@ We follow [Conventional Commits](https://www.conventionalcommits.org/) specifica
201207- ` ci ` : CI/CD changes
202208
203209** Examples:**
210+
204211```
205212feat(server): add Kubernetes runtime support
206213fix(execd): resolve memory leak in session cleanup
@@ -249,6 +256,7 @@ def create_sandbox(
249256```
250257
251258** Running Linter:**
259+
252260``` bash
253261cd server
254262uv run ruff check src tests
@@ -275,6 +283,7 @@ result, _ := someOperation()
275283```
276284
277285** Running Formatter:**
286+
278287``` bash
279288cd components/execd
280289gofmt -w .
@@ -348,6 +357,7 @@ async def test_invalid_timeout():
348357```
349358
350359** Running Tests:**
360+
351361``` bash
352362cd server
353363uv run pytest
@@ -371,6 +381,7 @@ func TestController_Execute_Python(t *testing.T) {
371381```
372382
373383** Running Tests:**
384+
374385``` bash
375386cd components/execd
376387go test ./pkg/...
@@ -419,19 +430,23 @@ When creating a PR, fill out the template:
419430
420431``` markdown
421432# Summary
433+
422434- What is changing and why?
423435
424436# Testing
437+
425438- [ ] Not run (explain why)
426439- [ ] Unit tests
427440- [ ] Integration tests
428441- [ ] e2e / manual verification
429442
430443# Breaking Changes
444+
431445- [ ] None
432446- [ ] Yes (describe impact and migration path)
433447
434448# Checklist
449+
435450- [ ] Linked Issue or clearly described motivation
436451- [ ] Added/updated docs (if needed)
437452- [ ] Added/updated tests (if needed)
@@ -442,6 +457,7 @@ When creating a PR, fill out the template:
442457### Pull Request Guidelines
443458
444459** Do:**
460+
445461- Keep PRs focused and reasonably sized (< 500 lines if possible)
446462- Write clear PR descriptions with motivation and context
447463- Link related issues
@@ -450,6 +466,7 @@ When creating a PR, fill out the template:
450466- Ensure CI passes before requesting review
451467
452468** Don't:**
469+
453470- Mix multiple unrelated changes in one PR
454471- Submit PRs with failing tests
455472- Ignore code review feedback
@@ -469,18 +486,21 @@ When creating a PR, fill out the template:
469486### GitHub Issues
470487
471488Use GitHub Issues for:
489+
472490- Bug reports
473491- Feature requests
474492- Documentation improvements
475493- Questions about implementation
476494
477495** Bug Report Template:**
496+
478497``` markdown
479498** Description**
480499A clear description of the bug.
481500
482501** To Reproduce**
483502Steps to reproduce the behavior:
503+
4845041 . Create sandbox with...
4855052 . Execute command...
4865063 . See error
@@ -489,6 +509,7 @@ Steps to reproduce the behavior:
489509What you expected to happen.
490510
491511** Environment**
512+
492513- OpenSandbox version:
493514- Runtime (Docker/K8s):
494515- OS:
@@ -501,6 +522,7 @@ Logs, screenshots, or other relevant information.
501522### GitHub Discussions
502523
503524Use GitHub Discussions for:
525+
504526- General questions
505527- Design discussions
506528- Brainstorming ideas
@@ -516,16 +538,17 @@ Use GitHub Discussions for:
516538
517539### Documentation
518540
519- - [ Architecture Overview] ( architecture.md )
520- - [ Server Development Guide] ( ../ server/DEVELOPMENT.md)
521- - [ execd Development Guide] ( ../ components/execd/DEVELOPMENT.md)
522- - [ OpenAPI Specifications] ( ../ specs/README.md)
523- - [ Python SDK Documentation] ( ../ sdks/sandbox/python/README.md)
524- - [ Java/Kotlin SDK Documentation] ( ../ sdks/sandbox/kotlin/README.md)
541+ - [ Architecture Overview] ( docs/ architecture.md)
542+ - [ Server Development Guide] ( server/DEVELOPMENT.md )
543+ - [ execd Development Guide] ( components/execd/DEVELOPMENT.md )
544+ - [ OpenAPI Specifications] ( specs/README.md )
545+ - [ Python SDK Documentation] ( sdks/sandbox/python/README.md )
546+ - [ Java/Kotlin SDK Documentation] ( sdks/sandbox/kotlin/README.md )
525547
526548### Examples
527549
528- Browse [ examples/] ( ../examples/ ) for real-world usage patterns:
550+ Browse [ examples/] ( examples/ ) for real-world usage patterns:
551+
529552- Code Interpreter integration
530553- AI Coding Agent integrations (Claude Code, Gemini CLI, etc.)
531554- Browser automation (Chrome, Playwright)
@@ -547,4 +570,4 @@ If you have suggestions for improving this contributing guide, please open an is
547570
548571## License
549572
550- By contributing to OpenSandbox, you agree that your contributions will be licensed under the [ Apache 2.0 License] ( ../ LICENSE) .
573+ By contributing to OpenSandbox, you agree that your contributions will be licensed under the [ Apache 2.0 License] ( LICENSE ) .
0 commit comments