|
2 | 2 |
|
3 | 3 | We welcome contributions to Quarto! |
4 | 4 |
|
| 5 | +Participation in this project is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). |
| 6 | +By taking part, you agree to uphold it. |
| 7 | + |
5 | 8 | You can contribute in many ways: |
6 | 9 |
|
7 | 10 | - By opening issues to provide feedback and share ideas. |
8 | | -- By fixing typos in documentation |
9 | | -- By submitting Pull Request (PR) to fix opened issues |
10 | | -- By submitting Pull Request (PR) to suggest new features (it is considered good practice to open an issue for discussion before working on a pull request for a new feature). |
| 11 | +- By fixing typos in documentation. |
| 12 | +- By submitting a Pull Request (PR) to fix an open issue. |
| 13 | +- By submitting a PR to suggest a new feature. |
| 14 | + It is good practice to open a discussion before working on a PR for a new feature. |
| 15 | + |
| 16 | +## Choosing the right channel |
| 17 | + |
| 18 | +This repository is for the command-line program `quarto`. |
| 19 | +Please use the destination that matches your need so we can respond quickly. |
| 20 | + |
| 21 | +| You want to | Use | |
| 22 | +| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | |
| 23 | +| Report a bug or unexpected behaviour. | [Bug report issue form](https://github.com/quarto-dev/quarto-cli/issues/new?template=bug_report.yml). | |
| 24 | +| Report an issue on quarto.org or suggest a documentation improvement. | [Documentation issue form](https://github.com/quarto-dev/quarto-cli/issues/new?template=documentation.yml). | |
| 25 | +| Suggest a new or missing feature. | [Feature Requests discussions](https://github.com/quarto-dev/quarto-cli/discussions/categories/feature-requests). | |
| 26 | +| Ask for help or ask a usage question. | [Q&A discussions](https://github.com/quarto-dev/quarto-cli/discussions/categories/q-a). | |
| 27 | +| Share what you built with Quarto. | [Show and Tell discussions](https://github.com/quarto-dev/quarto-cli/discussions/categories/show-and-tell). | |
| 28 | + |
| 29 | +Some issues belong to other repositories: |
| 30 | + |
| 31 | +- Visual Editor or the Visual Studio Code / Positron extension: <https://github.com/quarto-dev/quarto>. |
| 32 | +- RStudio: <https://github.com/rstudio/rstudio>. |
| 33 | +- Positron: <https://github.com/posit-dev/positron>. |
11 | 34 |
|
12 | 35 | ## Opening an issue |
13 | 36 |
|
14 | 37 | Before opening an issue, please search [existing issues](https://github.com/quarto-dev/quarto-cli/issues) to avoid duplicates. |
15 | 38 |
|
16 | | -When reporting a bug, include a minimal reproducible example. For feature requests, describe the use case and expected behavior. |
| 39 | +When reporting a bug, please: |
| 40 | + |
| 41 | +- Check that the issue persists on the [latest pre-release](https://github.com/quarto-dev/quarto-cli/releases). |
| 42 | +- Include a minimal, fully reproducible example as a self-contained Quarto document or a link to a Git repository. |
| 43 | +- Include the output of `quarto check` so we know which versions you are running. |
| 44 | +- Follow the [Bug Reports guide](https://quarto.org/bug-reports.html) to format your report. |
| 45 | + |
| 46 | +The [bug report form](https://github.com/quarto-dev/quarto-cli/issues/new?template=bug_report.yml) shows the syntax for sharing a Quarto document inside an issue. |
| 47 | + |
| 48 | +For documentation issues, add a link to the page you are referring to and a screenshot when relevant using the [Documentation issue form](https://github.com/quarto-dev/quarto-cli/issues/new?template=documentation.yml). |
17 | 49 |
|
18 | | -### Using AI tools to investigate |
| 50 | +## Starting a discussion |
| 51 | + |
| 52 | +Discussions are the right place for ideas, questions, and showcases. |
| 53 | +Before starting one, please search [existing discussions](https://github.com/quarto-dev/quarto-cli/discussions) and add to an existing thread when one already covers your topic. |
| 54 | + |
| 55 | +- [Feature Requests](https://github.com/quarto-dev/quarto-cli/discussions/categories/feature-requests): describe what you want to achieve and why it matters, so we can understand and prioritise it. |
| 56 | +- [Q&A](https://github.com/quarto-dev/quarto-cli/discussions/categories/q-a): ask for help, ideally with a complete self-contained reproducible example. |
| 57 | +- [Show and Tell](https://github.com/quarto-dev/quarto-cli/discussions/categories/show-and-tell): share a project, a tip, or a use case. |
| 58 | + |
| 59 | +## Using AI tools to investigate |
19 | 60 |
|
20 | 61 | If you are using an AI assistant to help investigate a bug or prepare an issue, point it to the Quarto codebase before asking it to analyze the problem: |
21 | 62 |
|
22 | | -- **[DeepWiki](https://deepwiki.com/quarto-dev/quarto-cli)** — AI-indexed documentation for the repository. Available as a web UI for human queries and as an [MCP server](https://docs.devin.ai/work-with-devin/deepwiki-mcp) to give your AI assistant direct access. Useful for understanding architecture, finding relevant source files, and asking questions about how Quarto works internally. |
23 | | -- **[Context7](https://context7.com)** — Provides up-to-date Quarto documentation and related tool docs. Available as a web UI, a [cli tool](https://context7.com/docs/clients/cli) and as an [MCP server](https://context7.com/docs/resources/all-clients) so AI assistants can fetch current docs on demand. |
24 | | -- **`https://quarto.org/llms.txt`** — Machine-readable index of Quarto documentation, following the [llms.txt convention](https://llmstxt.org/). Point your AI assistant at this URL to give it a structured map of available documentation. |
25 | | -- **Clone the repo** — AI tools that can run code or search files benefit from a local clone. Cloning the repository lets the AI search source files, trace code paths, and verify behavior directly rather than relying on potentially outdated training data. |
| 63 | +- **[DeepWiki](https://deepwiki.com/quarto-dev/quarto-cli)** — AI-indexed documentation for the repository. |
| 64 | + Available as a web UI for human queries and as an [MCP server](https://docs.devin.ai/work-with-devin/deepwiki-mcp) to give your AI assistant direct access. |
| 65 | + Useful for understanding architecture, finding relevant source files, and asking questions about how Quarto works internally. |
| 66 | +- **[Context7](https://context7.com)** — Provides up-to-date Quarto documentation and related tool docs. |
| 67 | + Available as a web UI, a [cli tool](https://context7.com/docs/clients/cli) and as an [MCP server](https://context7.com/docs/resources/all-clients) so AI assistants can fetch current docs on demand. |
| 68 | +- **`https://quarto.org/llms.txt`** — Machine-readable index of Quarto documentation, following the [llms.txt convention](https://llmstxt.org/). |
| 69 | + Point your AI assistant at this URL to give it a structured map of available documentation. |
| 70 | +- **Clone the repo** — AI tools that can run code or search files benefit from a local clone. |
| 71 | + Cloning the repository lets the AI search source files, trace code paths, and verify behavior directly rather than relying on potentially outdated training data. |
26 | 72 |
|
27 | 73 | Grounding your AI assistant in the actual codebase leads to more accurate root cause analysis and better-quality issue reports. |
28 | 74 |
|
29 | | -## To submit a contribution using a Pull Request |
| 75 | +## AI-assisted contributions |
| 76 | + |
| 77 | +AI assistants are welcome to help you investigate, write, and prepare a contribution. |
| 78 | +They are accepted only when a human contributor has reviewed, tested, and verified the submission before opening it. |
| 79 | + |
| 80 | +Issues and pull requests opened by autonomous AI agents acting without human oversight are not accepted. |
| 81 | +The [Code of Conduct](CODE_OF_CONDUCT.md) names autonomous agents such as OpenClaw as an example, and treats a first offence as account-bannable. |
| 82 | + |
| 83 | +If an AI assistant helped prepare a PR, please complete the AI-assisted section in the [pull request template](pull_request_template.md) so reviewers know how it was grounded and verified. |
| 84 | + |
| 85 | +## Submitting a pull request |
| 86 | + |
| 87 | +1. [Fork](https://github.com/quarto-dev/quarto-cli/fork) the repository, clone it locally, and make your changes in a new branch specific to the PR. |
| 88 | + For example: |
| 89 | + |
| 90 | + ```bash |
| 91 | + # clone your fork |
| 92 | + $ git clone https://github.com/<username>/quarto-cli |
30 | 93 |
|
31 | | -1. [Fork](https://github.com/quarto-dev/quarto-cli/fork) the repository, clone it locally, and make your changes in a new branch specific to the PR. For example: |
| 94 | + # configure for your platform (./configure.sh for linux/mac or ./configure.cmd for Windows) |
| 95 | + $ cd quarto-cli |
| 96 | + $ ./configure.sh |
32 | 97 |
|
33 | | - ```bash |
34 | | - # clone your fork |
35 | | - $ git clone https://github.com/<username>/quarto-cli |
| 98 | + # checkout a new branch |
| 99 | + $ git checkout -b bugfix/myfix |
| 100 | + ``` |
36 | 101 |
|
37 | | - # configure for your platform (./configure.sh for linux/mac or ./configure.cmd for Windows) |
38 | | - $ cd quarto-cli |
39 | | - $ ./configure.sh |
| 102 | +2. Submit the [pull request](https://help.github.com/articles/using-pull-requests). |
| 103 | + It is ok to submit as a draft if you are still working on it but would like some feedback from us. |
| 104 | + It is always good to share in the open that you are working on it. |
40 | 105 |
|
41 | | - # checkout a new branch |
42 | | - $ git checkout -b bugfix/myfix |
43 | | - ``` |
| 106 | +Before you open a PR, please check that you have (when applicable): |
44 | 107 |
|
45 | | -2. Submit the [pull request](https://help.github.com/articles/using-pull-requests). It is ok to submit as a draft if you are still working on it but would like some feedback from us. It is always good to share in the open that you are working on it. |
| 108 | +- Referenced the GitHub issue this PR closes. |
| 109 | +- Updated the relevant changelog in `news/changelog-{version}.md`. |
| 110 | +- Ensured the present test suite passes. |
| 111 | +- Added new tests for your change. |
| 112 | +- Opened a linked documentation PR in [Quarto's website repo](https://github.com/quarto-dev/quarto-web/) when behaviour or documentation changes. |
46 | 113 |
|
47 | | -We'll try to be as responsive as possible in reviewing and accepting pull requests. Very much appreciate your contributions! |
| 114 | +We'll try to be as responsive as possible in reviewing and accepting pull requests. |
| 115 | +Very much appreciate your contributions! |
0 commit comments