Skip to content

Commit 21a8a77

Browse files
treotreo
authored
Merge pull request #18 from XpressAI/fahreza/contributor-guide
📝 Add Contributing Guide
2 parents e6bcff0 + 40086a8 commit 21a8a77

File tree

3 files changed

+194
-3
lines changed

3 files changed

+194
-3
lines changed

‎README.md‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -139,9 +139,15 @@ The core principles and APIs are stable for production use.
139139
### Contributing
140140

141141
#### Running Tests
142-
Tests are implemented using pytest. If you are using PyCharm to run them, you
143-
will need to configure it to also show logging output. That way some failures
144-
will be a lot easier to debug.
142+
Tests are implemented using pytest.
143+
144+
```bash
145+
# From the root xaibo directory
146+
uv sync --all-extras
147+
uv run pytest
148+
```
149+
150+
If you are using PyCharm to run them, you will need to configure it to also show logging output. That way some failures will be a lot easier to debug.
145151

146152
Go to File > Settings > Advanced Settings > Python and check the option
147153
`Pytest: do not add "--no-header --no-summary -q"`.

‎docs/how-to/contribute/contributing.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
# Contribute to Xaibo
2+
3+
This guide will walk you through everything you need to know to contribute to the Xaibo AI agent framework.
4+
5+
## Prerequisites
6+
7+
Before you begin, make sure you have the following installed:
8+
9+
- [uv](https://docs.astral.sh/uv/) - Python package manager
10+
- [Node.js](https://nodejs.org/) - JavaScript runtime
11+
- [pnpm](https://pnpm.io/) - Node.js package manager
12+
13+
## Local Xaibo Setup
14+
15+
Clone the repository:
16+
17+
```bash
18+
git clone https://github.com/XpressAI/xaibo
19+
cd xaibo
20+
```
21+
22+
Install dependencies:
23+
24+
```bash
25+
uv sync
26+
```
27+
28+
## Contributing to Xaibo Core
29+
30+
The core framework is located at [`src/xaibo`](https://github.com/XpressAI/xaibo/tree/main/src/xaibo).
31+
32+
### Testing Your Core Changes
33+
34+
The `uvx` command allows you to point to your local development version instead of the installed package.
35+
36+
Create a test directory alongside your xaibo repo:
37+
38+
```bash
39+
# From your working directory, create a test folder
40+
mkdir ../test_new_feature
41+
cd ../test_new_feature
42+
```
43+
44+
This gives you a clean environment separate from your development code:
45+
46+
```
47+
working_dir/
48+
├── xaibo/ # Your cloned repo with your changes
49+
└── test_new_feature/ # Your test directory (you are here)
50+
```
51+
52+
Initialize a test agent using your local code:
53+
54+
```bash
55+
uvx ../xaibo init my_test_agent
56+
```
57+
58+
The `uvx` command points to your local xaibo directory (`../xaibo`) allowing you to test your changes directly.
59+
60+
### Running the Test Suite
61+
62+
Before pushing your PR, ensure that it doesn't break existing features by running the test suite.
63+
64+
First, make sure you have all dependencies including test dependencies installed:
65+
66+
```bash
67+
# From the root xaibo directory
68+
uv sync --all-extras
69+
```
70+
71+
Then run the test suite:
72+
73+
```bash
74+
uv run pytest
75+
```
76+
77+
!!! info "API Provider Integration Tests"
78+
79+
Integration tests for API providers will be skipped if no API keys are available in the environment. To run these tests, make sure you have the required API keys configured in your environment variables.
80+
81+
!!! tip "PyCharm Configuration"
82+
83+
If you're using PyCharm to run tests, you'll need to configure it to show logging output for easier debugging of test failures.
84+
85+
Go to **File > Settings > Advanced Settings > Python** and check the option: `Pytest: do not add "--no-header --no-summary -q"`.
86+
87+
## Contributing to Xaibo UI
88+
89+
The UI frontend is located at [`ui/`](https://github.com/XpressAI/xaibo/tree/main/ui).
90+
91+
Our UI stack includes:
92+
- **Svelte 5** - Frontend framework
93+
- **Houdini GraphQL** - Frontend GraphQL client ([houdinigraphql.com](https://houdinigraphql.com/))
94+
- **Strawberry** - Server-side GraphQL server ([strawberry.rocks](https://strawberry.rocks/)) - see implementation at [`src/xaibo/api/graphql`](https://github.com/XpressAI/xaibo/tree/main/ui/src/lib/graphql)
95+
96+
### Setting Up UI Development
97+
98+
Navigate to the UI directory and install dependencies:
99+
100+
```bash
101+
# From the root xaibo directory
102+
cd ui
103+
pnpm install
104+
```
105+
106+
Start the development server:
107+
108+
```bash
109+
pnpm run dev
110+
```
111+
112+
You'll see output like this, indicating the server is running:
113+
114+
```
115+
VITE v6.2.1 ready in 4584 ms
116+
117+
➜ Local: http://localhost:5173/
118+
➜ Network: use --host to expose
119+
➜ press h + enter to show help
120+
```
121+
122+
### Running a Xaibo Instance
123+
124+
The UI development server needs a running Xaibo instance to connect to, otherwise it'll be blank.
125+
126+
Run a Xaibo instance in another terminal tab:
127+
128+
```bash
129+
# From the root directory
130+
uv run xaibo dev
131+
```
132+
133+
### View Your Changes
134+
135+
Now you can visit `http://localhost:5173/` to see your UI changes in real-time as you work.
136+
137+
## Contributing to Xaibo Documentation
138+
139+
Our documentation uses [MkDocs](https://www.mkdocs.org/) with the [Material theme](https://squidfunk.github.io/mkdocs-material/) and follows the [Divio documentation system](https://docs.divio.com/documentation-system/).
140+
141+
### Working with Documentation
142+
143+
In the Xaibo base directory, start the local documentation server:
144+
145+
```bash
146+
uv run mkdocs serve
147+
```
148+
149+
### Adding New Documentation
150+
151+
Create your markdown files in the appropriate directory and update the `mkdocs.yml` configuration file to include your new pages.
152+
153+
Follow the Divio documentation principles:
154+
155+
- **Tutorials**: Learning-oriented, step-by-step guides for beginners
156+
- **How-to guides**: Problem-oriented, specific task instructions
157+
- **Reference**: Information-oriented, technical specifications
158+
- **Explanation**: Understanding-oriented, conceptual background
159+
160+
## Other Ways to Contribute
161+
162+
Aside from contributing to the core framework, UI, and documentation, you can also help by:
163+
164+
### Reporting Issues and Feature Requests
165+
166+
For bugs:
167+
168+
- Search existing [issues](https://github.com/XpressAI/xaibo/issues) first
169+
- Create a new issue with steps to reproduce, expected vs actual behavior, and your environment details
170+
171+
For feature requests:
172+
173+
- Check if someone has already suggested it
174+
- Open a new issue describing the problem it solves and why it would be useful
175+
176+
## Getting Help
177+
178+
If you need help or have questions, check the existing [issues](https://github.com/XpressAI/xaibo/issues) or open a new one for support.
179+
180+
Thank you for contributing to Xaibo! Your contributions help make AI agent development more accessible and powerful for everyone.
181+
182+
**Join our community**: Connect with other contributors and users in our [Discord server](https://discord.gg/uASMzSSVKe) 🚀

‎mkdocs.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,9 @@ nav:
134134
- OpenAI Chat Completions API: how-to/deployment/openai-api.md
135135
- OpenAI Responses API: how-to/api/openai-responses-quickstart.md
136136
- MCP Server: how-to/deployment/mcp-server.md
137+
- Contribute:
138+
- Contributing: how-to/contribute/contributing.md
139+
137140
- Reference:
138141
- reference/index.md
139142
- Configuration:

0 commit comments

Comments
 (0)