Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
255 lines (183 loc) · 7.66 KB

CONTRIBUTING.md

File metadata and controls

255 lines (183 loc) · 7.66 KB
Raw

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
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:

cargo build

The resulting executable will be in target/debug/sqlpage.

Release mode

To build the project in release mode:

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 --all to format your Rust code
  • Run cargo clippy to catch common mistakes and improve code quality
  • All code must pass the following checks:
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings

Frontend

We use Biome for linting and formatting of the frontend code, and TypeScript to typecheck it.

npm install # once
npm run format # apply formatting
npm test # the check CI runs: biome, typecheck, and the frontend unit tests

npm test checks the entire frontend codebase (html, css, js, ts).

Testing

Rust Tests

Run the backend tests:

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:

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/. Key areas covered include:

Component tests use deterministic SQL applications under tests/end-to-end/fixtures/<suite>/. Each suite contains an index.sql page and a test.ts file. Import test and expect from ../../fixture; the shared fixture opens the matching SQL page before every test and waits for all SQLPage components to initialize. Prefer role, label, and text locators over CSS selectors when the assertion does not specifically concern generated markup.

Keep official-site smoke and integration tests in root-level *.spec.ts files. Component behavior tests should render real components through their SQL fixture; do not inject component markup or invoke SQLPage's JavaScript initialization functions directly. Parameterized fixtures may accept request variables when several tests need the same component with different data.

Start a sqlpage instance pointed to the official site source code

cd examples/official-site
cargo run

Run the tests

In a separate terminal, run the tests:

npm install
cd tests/end-to-end
npx playwright install chromium
npm run test

Playwright starts the component fixture server on port 8081 automatically. The official-site server on port 8080 must still be started separately as shown above.

Documentation

Component Documentation

When adding new components, comprehensive documentation is required. Example from a component documentation:

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|INTEGER|JSON|ICON|COLOR|HTML|REAL|TIMESTAMP|URL', false, true);

-- Use description_md instead of description when the text contains markdown
INSERT INTO parameter(component, name, description_md, type, top_level, optional)
VALUES ('component_name', 'other_param', 'Set to `true` to see [the docs](/documentation.sql).', 'BOOLEAN', true, 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/.

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:

-- 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|INTEGER|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:
git checkout -b feature/your-feature-name
  1. Make your changes, ensuring:
  • All tests pass
  • Code is properly formatted
  • New features are documented
  • tests cover new functionality
  • CHANGELOG.md has an entry for any user-visible change

  1. Push your changes and create a Pull Request

  2. 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, typechecking and unit tests (npm test)
    • Test against multiple databases (SQLite, PostgreSQL, MySQL, MSSQL, Oracle, and ODBC)

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.