chore: import upstream snapshot with attribution

2026-07-13 12:31:57 +08:00
commit d718c5a372
986 changed files with 74597 additions and 0 deletions
@@ -0,0 +1,233 @@
+# Contributing to SQLPage
+
+Thank you for your interest in contributing to SQLPage! This document will guide you through the contribution process.
+
+## Development Setup
+
+1. Install Rust and Cargo (latest stable version): https://www.rust-lang.org/tools/install
+2. If you contribute to the frontend, install Node.js too for frontend tooling: https://nodejs.org/en/download/
+3. Clone the repository
+
+```bash
+git clone https://github.com/sqlpage/sqlpage
+cd sqlpage
+```
+
+## Building the project
+
+The first time you build the project,
+dependencies will be downloaded, so you will need internet access,
+and the build may take a while.
+
+Run the following command from the root of the repository to build the project in development mode:
+
+```bash
+cargo build
+```
+
+The resulting executable will be in `target/debug/sqlpage`.
+
+### Release mode
+
+To build the project in release mode:
+
+```bash
+cargo build --release
+```
+
+The resulting executable will be in `target/release/sqlpage`.
+
+### ODBC build modes
+
+SQLPage can either be built with an integrated odbc driver manager (static linking),
+or depend on having one already installed on the system where it is running (dynamic linking).
+
+- Dynamic ODBC (default): `cargo build`
+- Static ODBC (Linux and MacOS only): `cargo build --features odbc-static`
+
+Windows comes with ODBC pre-installed; SQLPage cannot statically link to the unixODBC driver manager on windows.
+
+## Code Style and Linting
+
+### Rust
+
+- Use `cargo fmt` to format your Rust code
+- Run `cargo clippy` to catch common mistakes and improve code quality
+- All code must pass the following checks:
+
+```bash
+cargo fmt --all -- --check
+cargo clippy
+```
+
+### Frontend
+
+We use Biome for linting and formatting of the frontend code.
+
+```bash
+npx @biomejs/biome check .
+```
+
+This will check the entire codebase (html, css, js).
+
+## Testing
+
+### Rust Tests
+
+Run the backend tests:
+
+```bash
+cargo test
+```
+
+By default, the tests are run against an SQLite in-memory database.
+
+If you want to run them against another database,
+start a database server with `docker compose up database_name` (mssql, mysql, mariadb, or postgres)
+and run the tests with the `DATABASE_URL` environment variable pointing to the database:
+
+```bash
+docker compose up mssql # or mysql, mariadb, postgres
+export DATABASE_URL=mssql://root:Password123!@localhost/sqlpage
+cargo test
+```
+
+### End-to-End Tests
+
+We use Playwright for end-to-end testing of dynamic frontend features.
+Tests are located in [`tests/end-to-end/`](./tests/end-to-end/). Key areas covered include:
+
+#### Start a sqlpage instance pointed to the official site source code
+
+```bash
+cd examples/official-site
+cargo run
+```
+
+#### Run the tests
+
+In a separate terminal, run the tests:
+
+```bash
+cd tests/end-to-end
+npm install
+npx playwright install chromium
+npm run test
+```
+
+## Documentation
+
+### Component Documentation
+
+When adding new components, comprehensive documentation is required. Example from a component documentation:
+
+```sql
+INSERT INTO component(name, icon, description, introduced_in_version) VALUES
+    ('component_name', 'icon_name', 'Description of the component', 'version');
+
+-- Document all parameters
+INSERT INTO parameter(component, name, description, type, top_level, optional)
+VALUES ('component_name', 'param_name', 'param_description', 'TEXT|BOOLEAN|NUMBER|JSON|ICON|COLOR', false, true);
+
+-- Include usage examples
+INSERT INTO example(component, description, properties) VALUES
+    ('component_name', 'Example description in markdown', JSON('[
+{"component": "new_component_name", "top_level_property_1": "value1", "top_level_property_2": "value2"},
+{"row_level_property_1": "value1", "row_level_property_2": "value2"}
+]'));
+```
+
+Component documentation is stored in [`./examples/official-site/sqlpage/migrations/`](./examples/official-site/sqlpage/migrations/).
+
+If you are editing an existing component, edit the existing sql documentation file directly.
+If you are adding a new component, add a new sql file in the folder, and add the appropriate insert statements above.
+
+### SQLPage Function Documentation
+
+When adding new SQLPage functions, document them using a SQL migrations. Example structure:
+
+```sql
+-- Function Definition
+INSERT INTO sqlpage_functions (
+    "name",
+    "introduced_in_version",
+    "icon",
+    "description_md"
+)
+VALUES (
+    'your_function_name',
+    '1.0.0',
+    'function-icon-name',
+    'Description of what the function does.
+
+### Example
+
+    select ''text'' as component, sqlpage.your_function_name(''parameter'') as result;
+
+Additional markdown documentation, usage notes, and examples go here.
+');
+
+-- Function Parameters
+INSERT INTO sqlpage_function_parameters (
+    "function",
+    "index",
+    "name",
+    "description_md",
+    "type"
+)
+VALUES (
+    'your_function_name',
+    1,
+    'parameter_name',
+    'Description of what this parameter does and how to use it.',
+    'TEXT|BOOLEAN|NUMBER|JSON'
+);
+```
+
+Key elements to include in function documentation:
+
+- Clear description of the function's purpose
+- Version number where the function was introduced
+- Appropriate icon
+- Markdown-formatted documentation with examples
+- All parameters documented with clear descriptions and types
+- Security considerations if applicable
+- Example usage scenarios
+
+## Pull Request Process
+
+1. Create a new branch for your feature/fix:
+
+```bash
+git checkout -b feature/your-feature-name
+```
+
+2. Make your changes, ensuring:
+
+- All tests pass
+- Code is properly formatted
+- New features are documented
+- tests cover new functionality
+
+3. Push your changes and create a Pull Request
+
+4. CI Checks
+   Our CI pipeline will automatically:
+   - Run Rust formatting and clippy checks
+   - Execute all tests across multiple platforms (Linux, Windows)
+   - Build Docker images for multiple architectures
+   - Run frontend linting with Biome
+   - Test against multiple databases (PostgreSQL, MySQL, MSSQL)
+
+## Release Process
+
+Releases are automated when pushing tags that match the pattern `v*` (e.g., `v1.0.0`). The CI pipeline will:
+
+- Build and test the code
+- Create Docker images for multiple architectures
+- Push images to Docker Hub
+- Create GitHub releases
+
+## Questions?
+
+If you have any questions, feel free to open an issue or discussion on GitHub.