Skip to content

Commit 4623535

Browse files
lovasoalovasoa
committed
add contribution guide
1 parent ebf19aa commit 4623535

File tree

2 files changed

+198
-1
lines changed

2 files changed

+198
-1
lines changed

‎CONTRIBUTING.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
# Contributing to SQLPage
2+
3+
Thank you for your interest in contributing to SQLPage! This document will guide you through the contribution process.
4+
5+
## Development Setup
6+
7+
1. Install Rust and Cargo (latest stable version): https://www.rust-lang.org/tools/install
8+
2. If you contribute to the frontend, install Node.js too for frontend tooling: https://nodejs.org/en/download/
9+
3. Clone the repository
10+
11+
```bash
12+
git clone https://github.com/sqlpage/sqlpage
13+
cd sqlpage
14+
```
15+
16+
## Code Style and Linting
17+
18+
### Rust
19+
- Use `cargo fmt` to format your Rust code
20+
- Run `cargo clippy` to catch common mistakes and improve code quality
21+
- All code must pass the following checks:
22+
```bash
23+
cargo fmt --all -- --check
24+
cargo clippy
25+
```
26+
27+
### Frontend
28+
29+
We use Biome for linting and formatting of the frontend code.
30+
31+
```bash
32+
npx @biomejs/biome check .
33+
```
34+
This will check the entire codebase (html, css, js).
35+
36+
## Testing
37+
38+
### Rust Tests
39+
40+
Run the backend tests:
41+
42+
```bash
43+
cargo test
44+
```
45+
46+
By default, the tests are run against an SQLite in-memory database.
47+
48+
If you want to run them against another database,
49+
start a database server with `docker compose up database_name` (mssql, mysql, mariadb, or postgres)
50+
and run the tests with the `DATABASE_URL` environment variable pointing to the database:
51+
52+
```bash
53+
docker compose up mssql # or mysql, mariadb, postgres
54+
export DATABASE_URL=mssql://root:Password123!@localhost/sqlpage
55+
cargo test
56+
```
57+
58+
### End-to-End Tests
59+
We use Playwright for end-to-end testing of dynamic frontend features.
60+
Tests are located in [`tests/end-to-end/`](./tests/end-to-end/). Key areas covered include:
61+
62+
#### Start a sqlpage instance pointed to the official site source code
63+
64+
```bash
65+
cd examples/official-site
66+
cargo run
67+
```
68+
69+
#### Run the tests
70+
71+
In a separate terminal, run the tests:
72+
73+
```bash
74+
cd tests/end-to-end
75+
npm install
76+
npm run test
77+
```
78+
79+
## Documentation
80+
81+
### Component Documentation
82+
When adding new components, comprehensive documentation is required. Example from a component documentation:
83+
84+
```sql
85+
INSERT INTO component(name, icon, description, introduced_in_version) VALUES
86+
('component_name', 'icon_name', 'Description of the component', 'version');
87+
88+
-- Document all parameters
89+
INSERT INTO parameter(component, name, description, type, top_level, optional)
90+
VALUES ('component_name', 'param_name', 'param_description', 'TEXT|BOOLEAN|NUMBER|JSON|ICON|COLOR', false, true);
91+
92+
-- Include usage examples
93+
INSERT INTO example(component, description, properties) VALUES
94+
('component_name', 'Example description in markdown', JSON('[
95+
{"component": "new_component_name", "top_level_property_1": "value1", "top_level_property_2": "value2"},
96+
{"row_level_property_1": "value1", "row_level_property_2": "value2"}
97+
]'));
98+
```
99+
100+
Component documentation is stored in [`./examples/official-site/sqlpage/migrations/`](./examples/official-site/sqlpage/migrations/).
101+
102+
If you are editing an existing component, edit the existing sql documentation file directly.
103+
If you are adding a new component, add a new sql file in the folder, and add the appropriate insert statements above.
104+
105+
### SQLPage Function Documentation
106+
When adding new SQLPage functions, document them using a SQL migrations. Example structure:
107+
108+
```sql
109+
-- Function Definition
110+
INSERT INTO sqlpage_functions (
111+
"name",
112+
"introduced_in_version",
113+
"icon",
114+
"description_md"
115+
)
116+
VALUES (
117+
'your_function_name',
118+
'1.0.0',
119+
'function-icon-name',
120+
'Description of what the function does.
121+
122+
### Example
123+
124+
select ''text'' as component, sqlpage.your_function_name(''parameter'') as result;
125+
126+
Additional markdown documentation, usage notes, and examples go here.
127+
');
128+
129+
-- Function Parameters
130+
INSERT INTO sqlpage_function_parameters (
131+
"function",
132+
"index",
133+
"name",
134+
"description_md",
135+
"type"
136+
)
137+
VALUES (
138+
'your_function_name',
139+
1,
140+
'parameter_name',
141+
'Description of what this parameter does and how to use it.',
142+
'TEXT|BOOLEAN|NUMBER|JSON'
143+
);
144+
```
145+
146+
Key elements to include in function documentation:
147+
- Clear description of the function's purpose
148+
- Version number where the function was introduced
149+
- Appropriate icon
150+
- Markdown-formatted documentation with examples
151+
- All parameters documented with clear descriptions and types
152+
- Security considerations if applicable
153+
- Example usage scenarios
154+
155+
## Pull Request Process
156+
157+
1. Create a new branch for your feature/fix:
158+
```bash
159+
git checkout -b feature/your-feature-name
160+
```
161+
162+
2. Make your changes, ensuring:
163+
- All tests pass
164+
- Code is properly formatted
165+
- New features are documented
166+
- tests cover new functionality
167+
168+
3. Push your changes and create a Pull Request
169+
170+
4. CI Checks
171+
Our CI pipeline will automatically:
172+
- Run Rust formatting and clippy checks
173+
- Execute all tests across multiple platforms (Linux, Windows)
174+
- Build Docker images for multiple architectures
175+
- Run frontend linting with Biome
176+
- Test against multiple databases (PostgreSQL, MySQL, MSSQL)
177+
178+
5. Wait for review and address any feedback
179+
180+
## Release Process
181+
182+
Releases are automated when pushing tags that match the pattern `v*` (e.g., `v1.0.0`). The CI pipeline will:
183+
- Build and test the code
184+
- Create Docker images for multiple architectures
185+
- Push images to Docker Hub
186+
- Create GitHub releases
187+
188+
## Questions?
189+
190+
If you have any questions, feel free to open an issue or discussion on GitHub.

‎README.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -315,4 +315,11 @@ SQLPage is available for download on the from multiple sources:
315315
[![homebrew downloads](https://img.shields.io/homebrew/installs/dq/sqlpage?label=homebrew%20downloads&labelColor=%232e2a24&color=%23f9d094)](https://formulae.brew.sh/formula/sqlpage#default)
316316
[![Scoop Version](https://img.shields.io/scoop/v/sqlpage?labelColor=%23696573&color=%23d7d4db)](https://scoop.sh/#/apps?q=sqlpage&id=305b3437817cd197058954a2f76ac1cf0e444116)
317317
[![Crates.io Total Downloads](https://img.shields.io/crates/d/sqlpage?label=crates.io%20download&labelColor=%23264323&color=%23f9f7ec)](https://crates.io/crates/sqlpage)
318-
[![](https://img.shields.io/badge/Nix-pkg-rgb(126,%20185,%20227))](https://search.nixos.org/packages?channel=unstable&show=sqlpage&from=0&size=50&sort=relevance&type=packages&query=sqlpage)
318+
[![](https://img.shields.io/badge/Nix-pkg-rgb(126,%20185,%20227))](https://search.nixos.org/packages?channel=unstable&show=sqlpage&from=0&size=50&sort=relevance&type=packages&query=sqlpage)
319+
320+
## Contributing
321+
322+
We welcome contributions! SQLPage is built with Rust and uses
323+
vanilla javascript for its frontend parts.
324+
325+
Check out our [Contributing Guide](./CONTRIBUTING.md) for detailed instructions on development setup, testing, and pull request process.

0 commit comments

Comments
 (0)