Skip to content

Latest commit

 

History

History
91 lines (61 loc) · 5.35 KB

CONTRIBUTING.md

File metadata and controls

91 lines (61 loc) · 5.35 KB
Raw

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 [email protected].

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 Building 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.

Syntax

  • 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.

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.

Spelling

Examples

  • 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.
  • All examples should be self-contained and reproducible if possible, meaning that any example tables must be created as a part of the documentation.

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

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.