swadhin / contexa public

docs: add CONTRIBUTING.md with dev setup for all 7 languages

Swadhin Biswas committed 7 months ago
b502219
1 parent df9dda5
commit b502219
1 file changed
+167 -0
Showing 1 changed file+167-0
CONTRIBUTING.md
▼CONTRIBUTING.md
+167-0
@@ -0,0 +1,167 @@
1
+# Contributing to contexa
2
+
3
+Thank you for your interest in contributing to **contexa** — git-inspired context management for LLM agents.
4
+
5
+This is a polyglot monorepo with implementations in **Python, JavaScript/TypeScript, Rust, Go, Zig, Lua, and Elixir**. Contributions to any language are welcome.
6
+
7
+## Table of Contents
8
+
9
+- [Code of Conduct](#code-of-conduct)
10
+- [Getting Started](#getting-started)
11
+- [Development Setup](#development-setup)
12
+- [Running Tests](#running-tests)
13
+- [Submitting Changes](#submitting-changes)
14
+- [Code Style](#code-style)
15
+- [Labels](#labels)
16
+
17
+## Code of Conduct
18
+
19
+This project follows the [Contributor Covenant v2.1](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
20
+
21
+## Getting Started
22
+
23
+1. Fork the repository: <https://github.com/swadhinbiswas/contexa>
24
+2. Clone your fork:
25
+ ```bash
26
+ git clone https://github.com/<your-username>/contexa.git
27
+ cd contexa
28
+ ```
29
+3. Create a feature branch:
30
+ ```bash
31
+ git checkout -b feat/my-change
32
+ ```
33
+4. Make your changes, add tests, and ensure all tests pass.
34
+5. Push and open a pull request against `main`.
35
+
36
+## Development Setup
37
+
38
+Each language lives in its own top-level directory. You only need to install tooling for the language(s) you are working on.
39
+
40
+### Python (`PYTHON/`)
41
+
42
+- **Requires**: Python 3.9+ and [uv](https://docs.astral.sh/uv/)
43
+- **Setup**:
44
+ ```bash
45
+ cd PYTHON
46
+ uv sync
47
+ ```
48
+
49
+### JavaScript / TypeScript (`JS/`)
50
+
51
+- **Requires**: Node.js 18+ and npm
52
+- **Setup**:
53
+ ```bash
54
+ cd JS
55
+ npm install
56
+ ```
57
+
58
+### Rust (`RUST/`)
59
+
60
+- **Requires**: Rust 1.70+ (stable toolchain)
61
+- **Setup**:
62
+ ```bash
63
+ cd RUST
64
+ cargo build
65
+ ```
66
+
67
+### Go (`GO/`)
68
+
69
+- **Requires**: Go 1.21+
70
+- **Setup**:
71
+ ```bash
72
+ cd GO
73
+ go mod download
74
+ ```
75
+
76
+### Zig (`ZIG/`)
77
+
78
+- **Requires**: Zig 0.14.0 (latest stable)
79
+- **Setup**: No package manager needed; `zig build` handles everything.
80
+
81
+### Lua (`LUA/`)
82
+
83
+- **Requires**: Lua 5.3+ (5.4 recommended)
84
+- **Setup**: No package manager needed for development. [LuaRocks](https://luarocks.org/) is only needed for publishing.
85
+
86
+### Elixir (`ELIXIR/`)
87
+
88
+- **Requires**: Elixir 1.15+ and Erlang/OTP 26+
89
+- **Setup**:
90
+ ```bash
91
+ cd ELIXIR
92
+ mix deps.get
93
+ ```
94
+
95
+## Running Tests
96
+
97
+Run the tests for the language(s) you modified before submitting a PR.
98
+
99
+| Language | Command |
100
+|------------|------------------------------------------------|
101
+| Python | `cd PYTHON && uv run pytest -v` |
102
+| JavaScript | `cd JS && npm test` |
103
+| Rust | `cd RUST && cargo test` |
104
+| Go | `cd GO && go test ./...` |
105
+| Zig | `cd ZIG && zig build test` |
106
+| Lua | `cd LUA && lua test.lua` |
107
+| Elixir | `cd ELIXIR && mix test` |
108
+
109
+CI runs all 7 language test suites on every pull request. Your PR must pass all checks before it can be merged.
110
+
111
+## Submitting Changes
112
+
113
+1. **One concern per PR.** Keep pull requests focused on a single change.
114
+2. **Write tests.** If you add a feature or fix a bug, add or update the relevant tests.
115
+3. **Update docs.** If you change the public API surface, update the language-specific `README.md`.
116
+4. **Fill out the PR template.** Check the affected languages and ensure the checklist is complete.
117
+5. **Keep commits clean.** Use clear, descriptive commit messages. Squash fixup commits before requesting review.
118
+
119
+### Branch Naming Convention
120
+
121
+- `feat/<description>` — new features
122
+- `fix/<description>` — bug fixes
123
+- `docs/<description>` — documentation changes
124
+- `ci/<description>` — CI/build changes
125
+- `refactor/<description>` — code refactoring
126
+
127
+## Code Style
128
+
129
+- **Python**: Follow [PEP 8](https://peps.python.org/pep-0008/). The project uses [ruff](https://docs.astral.sh/ruff/) for linting.
130
+- **JavaScript/TypeScript**: Follow the existing style. Build with `tsup`.
131
+- **Rust**: Run `cargo fmt` and `cargo clippy` before committing.
132
+- **Go**: Run `gofmt` and `go vet`.
133
+- **Zig**: Follow the [Zig style guide](https://ziglang.org/documentation/master/#Style-Guide).
134
+- **Lua**: Follow the existing style in `LUA/contexa/`.
135
+- **Elixir**: Run `mix format` before committing.
136
+
137
+## Labels
138
+
139
+Issues and PRs are categorized with the following labels:
140
+
141
+### Language Labels
142
+
143
+| Label | Description |
144
+|-----------------|----------------------------|
145
+| `lang:python` | Python implementation |
146
+| `lang:js` | JavaScript implementation |
147
+| `lang:rust` | Rust implementation |
148
+| `lang:go` | Go implementation |
149
+| `lang:zig` | Zig implementation |
150
+| `lang:lua` | Lua implementation |
151
+| `lang:elixir` | Elixir implementation |
152
+
153
+### Type Labels
154
+
155
+| Label | Description |
156
+|--------------------|--------------------------------------|
157
+| `bug` | Something isn't working |
158
+| `enhancement` | New feature or request |
159
+| `documentation` | Improvements or additions to docs |
160
+| `good first issue` | Good for newcomers |
161
+| `help wanted` | Extra attention is needed |
162
+| `ci` | CI/CD and build system |
163
+| `question` | Further information is requested |
164
+
165
+---
166
+
167
+If you have questions, feel free to [open a discussion](https://github.com/swadhinbiswas/contexa/issues/new?template=question.yml) or reach out to [@swadhinbiswas](https://github.com/swadhinbiswas).
0
168