Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
110 lines (84 loc) · 8.33 KB

CONTRIBUTING.md

File metadata and controls

110 lines (84 loc) · 8.33 KB

Contributing

Code of Conduct

This project and everyone participating in it is governed by a Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to quack@duckdb.org.

Contributing to the DuckLake Documentation

Contributions to the DuckLake Documentation are welcome. To submit a contribution, please open a pull request in the duckdb/ducklake-web repository.

Adding a New Page

Thank you for contributing to the DuckLakeB documentation!

Each new page requires at least 2 edits:

  • Create new Markdown file (using the snake_case naming convention). Please follow the format of another .md file in the docs/stable folder.
  • Add a link to the new page within _data/menu_docs_stable.json. This populates the side menu.

When creating a PR, please check the box to "Allow edits from maintainers".

Style Guide

Please adhere the following style guide when submitting a pull request.

Some of this style guide is automated with GitHub Actions, but feel free to run scripts/lint.sh to run them locally.

Formatting

  • Use GitHub's Markdown syntax for formatting.
  • Do not hard-wrap lines in blocks of text.
  • Format code blocks with the appropriate language (e.g., ```sql CODE```).
  • For a SQL code block to start with DuckDB's D prompt, use the plsql language tag (e.g., ```plsql CODE```). The two use the same syntax highlighter as SQL, the only difference is the presence of the D prompt.
  • Code blocks using the batch language tag automatically receive $ prompt when rendered. To typeset a Bash code block without a prompt, use the bash language tag (e.g., ```batch CODE```). The two use the same syntax highlighter, the only difference is the absence of the prompt.
  • To display blocks of text without a language (e.g., output of a script), use ```text OUTPUT```.
  • To display error messages, use ```console ERROR MESSAGE```.
  • Quoted blocks (lines starting with >) are rendered as a colored box. The following box types are available: Note (default), Warning, Tip, Bestpractice, Deprecated.
  • Always format SQL code, variable names, function names, etc. as code. For example, when talking about the CREATE TABLE statement, the keywords should be formatted as code.
  • When presenting SQL statements, do not include the prompt (D ).
  • SQL statements should end with a semicolon (;) to allow readers to quickly paste them into a SQL console.
  • Tables with predominantly code output (e.g., the result of a DESCRIBE statement) should be prepended with an empty div that has the monospace_table class: <div class="monospace_table"></div>.
  • Tables where the headers should be center-aligned (opposed to the left-aligned default) should be prepended with an empty div that has the center_aligned_header_table class: <div class="center_aligned_header_table"></div>.
  • Do not introduce hard line breaks if possible. Therefore, avoid using the <br/> HTML tag and avoid double spaces at the end of a line in Markdown.
  • Single and double quote characters (' and ") are not converted to smart quotation marks automatically. To insert these, use “ ” and ‘ ’.
  • When referencing other articles, put their titles in quotes, e.g., see the [“DuckLake 0.3 with Iceberg Interoperability and Geometry Support” blog post]({% pust_url 2025-09-17-ducklake-03 %}).
  • For unordered lists, use *. If the list has multiple levels, use 4 spaces for indentation.

Tip

In VS Code, you can configure the Markdown All in One extension to use asterisk as the default marker when generating a table of content for a page using the following setting in settings.json: "markdown.extension.toc.unorderedList.marker": "*"

Headers

  • The title of the page should be encoded in the front matter's title property. The body of the page should not start with a repetition of this title.
  • In the body of the page, restrict the use of headers to the following levels: h2 (##), h3 (###), and h4 (####).
  • Use headline capitalization as defined in the Chicago Manual of Style.

SQL Style

  • Use 4 spaces for indentation.
  • Use uppercase SQL keywords, e.g., SELECT 42 AS x, 'hello world' AS y FROM ...;.
  • Use lowercase function names, e.g., SELECT cos(pi()), date_part('year', DATE '1992-09-20');.
  • Use snake case (lowercase with underscore separators) for table and column names, e.g., SELECT departure_time FROM train_services;
  • Add spaces around commas and operators, e.g., SELECT FROM tbl WHERE x > 42;.
  • Add a semicolon to the end of each SQL statement, e.g., SELECT 42 AS x;.
  • Commas should be placed at the end of each line.
  • Do not add clauses or expressions purely for aligning lines. For example, avoid adding WHERE 1 = 1 and WHERE true.
  • Do not include the DuckDB prompt. For example, avoid the following: D SELECT 42;.
  • Employing DuckDB's syntax extensions, e.g., the FROM-first syntax and GROUP BY ALL, is allowed but use them sparingly when introducing new features.
  • The returned tables should be formatted using the DuckDB CLI's markdown mode (.mode markdown) and NULL values rendered as NULL (.nullvalue NULL).
  • Output printed on the system console (e.g., in Python) and system messages (e.g., errors) should be formatted as code with the text language tag. For example: 
    ```text
Error: Constraint Error: Duplicate key "i: 1" violates primary key constraint.
```
  • To specify placeholders (or template-style code), use left angle and right angle characters, ⟨ and ⟩, also known as chevrons or angle brackets. These will be highlighted in red and typeset in monospace bold italic to draw the reader's attention to them.
    • For example, you could write: To create a table from a Parquet file, run: CREATE TABLE ⟨your_table_name⟩ AS FROM '⟨your_filename⟩.parquet'.
    • Copy the characters from here: ⟨⟩.
    • These characters are known in LaTeX code as \langle and \rangle.
    • Inline code snippets containing placeholders should be highlighted as SQL code. This can be achieved by appending {:.language-sql .highlight} after the code snippet (no space is required before the curly brace).
    • Avoid using arithmetic comparison characters, < and >, brackets, [ and ], braces, { and }, for this purpose.

Spelling

Example Code Snippets

  • Examples that illustrate the use of features are very welcome. Where applicable, consider starting the page with a few simple examples that demonstrate the most common uses of the feature described.
  • If possible, examples should be self-contained and reproducible. For example, the tables used in the example must be created as a part of the example code snippet.

Cross-References

  • Where applicable, add cross-references to relevant other pages in the documentation.
  • Use Jekyll's link tags to link to pages.
  • In most cases, linking related GitHub issues/discussions is discouraged. This allows the documentation to be self-contained.