Skip to content

Latest commit

 

History

History
121 lines (84 loc) · 6.99 KB

CONTRIBUTING.md

File metadata and controls

121 lines (84 loc) · 6.99 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 DuckDB Documentation

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

Eligibility

Before submitting a contribution, please check whether your contribution is eligible.

  1. Before creating a new page, please search the existing documentation for similar pages.
  2. In general, guides for third-party tools using DuckDB should not be included in the DuckDB documentation. Rather, these tools and their documentation should be collected in the awesome-duckdb community repository.

Adding a New Page

Thank you for contributing to the DuckDB documentation!

Each new page requires at least 2 edits:

  • The creation of a new Markdown page with the documentation. Please follow the format of another .md file in the docs folder.
  • Add a link to the new page within _data/menu_docs_dev.json. This populates the dropdown menus.

The addition of a new guide requires one additional edit:

  • Add a link to the new page within the Guides landing page: docs/guides/index.md

Before creating a pull request, please perform the following steps:

  • Preview your changes in the browser using the site build guide.
  • Run the linters with scripts/lint.sh to show potential issues and run scripts/lint.sh -f to perform the fixes for MarkdownLint.

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 HERE ```).
  • To display blocks of text without a language (e.g., output of a script), use ```text OUTPUT HERE ```.
  • Quoted blocks (lines starting with >) are rendered as a "Note" box.
  • 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 DuckDB prompt (D ).
  • SQL statements should end with a semicolon (;) to allow readers to quickly paste them into a SQL console.
  • Narrow tables should be prepended with an empty div that has the narrow table class: <div class="narrow_table"></div>.

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 SQL uppercase keywords, e.g., SELECT ... FROM ....
  • 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.
  • Use 4 spaces for indentation.

Python Style

  • Use 4 spaces for indentation.

Links

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 descriptive links:
    • ✅ see [the `COPY` statement](../../sql/statements/copy)
    • ❌ see [here](../../sql/statements/copy)
  • Use relative URLs without the .html extension:
    • ✅ ../../sql/statements/copy
    • ❌ ../../sql/statements/copy.html
    • ❌ /docs/sql/statements/copy
    • ❌ https://duckdb.org/docs/sql/statements/copy
  • Reference a specific section when possible:
    • ✅ ../../sql/statements/copy#copy-from
  • Do not link related GitHub issues/discussions. This allows the documentation to be self-contained.

Achive and Generated Pages

  • The archive pages (e.g., https://duckdb.org/docs/archive/0.8.1/) contain documentation for old versions of DuckDB. In general, we do not accept contributions to these pages – please target the latest version of the page when submitting your contributions.
  • Many of the documentation's pages are auto-generated. Before editing, please check the scripts/generate_all_docs.sh script. Do not edit the generated content, instead, edit the source files (often found in the duckdb repository).

Notice

We reserve full and final discretion over whether or not we will merge a pull request. Adhering to these guidelines is not a guarantee that your pull request will be merged.