Home

Contributing ❤️

Thanks for thinking about helping with dart.dev! You can contribute in a few ways.

Report an issue. If you find an issue larger than a small typo, we'd love for you to report it (and fix it if you want). To report an issue, go to the Report issues page and create the issue.
Fix a typo. The GitHub UI makes it easy to contribute small fixes, and you'll get credit for your contribution! To learn more, see Fix a small issue.
Fix a small known issue. If you found an issue in the Issues list and it's only going to require a few edits (excluding code samples) on a page, see Fix a small issue.
Fix a large known issue. If you found an issue in the Issues list and it's only going to require a few edits (excluding code samples) on a page, see Fix a large issue.

More info:

To avoid wasting your time, talk with us before you make any nontrivial pull request. The issue tracker is a good way to track your progress publicly, but we also use the #hackers-devrel channel on Flutter's Discord server.
We use the usual GitHub pull request process.
We follow the Google Developer Documentation Style Guide, with some additional conventions that we try to document in the site-shared repo. In particular, we use semantic line breaks.

Code of conduct

We pledge to maintain an open and welcoming environment. For details, see our code of conduct.

Fix a small issue

If you have found a small issue, such as a typo or a paragraph on one page that needs to be fixed, and no code samples need to be updated, follow the steps in this section.

Click the page icon at the upper right of the page.
Click the pencil icon to start editing the file.
Update the text in the file.
Commit your changes to a new branch in your forked repository and create a pull request.
We'll review your change. If we like the change, we'll approve and merge it. Normally, we'll review your fix within one working day, and your fix will appear online less than an hour after we merge your PR.

Note: If this is your first contribution to a Google project—welcome!—you'll need to sign the CLA.

Fix a large issue

If you have an issue that you want to fix, look for that issue in Issues and assign yourself to it. If the issue doesn't exist, create a new one and then assign yourself to it.

Next, fork the repo, make your changes, and generate a pull request. If your change involves code samples, adds/removes pages, or affects navigation, make sure to build the site so that you can see your changes locally. Additionally, if you updated any code samples, you will need to test your changes. To learn more see the following sections.

Note: If this is your first contribution to a Google project—welcome!—you'll need to sign the CLA.

Install Dart

The latest stable release of Dart is required to build the site and run its tooling. This can be the Dart included in the Flutter SDK. If you don't have Dart or need to update, follow the instructions at Get the Dart SDK.

If you already have Dart installed, verify it's on your path and already the latest stable version:

dart --version

Install Node.js

The latest stable LTS release of Node.js is required to build the site. If you don't have Node.js or need to update, download your computer's corresponding version and follow the instructions from the Node.js download archive. If you prefer, you can use a version manager such as nvm, and run nvm install from the repository's root directory.

If you already have Node installed, verify it's available on your path and already the latest stable version (currently 22.12 or later):

node --version

If your version is out of date, follow the update instructions for how you originally installed it.

Clone repo and submodules

Note

This repository has git submodules, which affects how you clone it. The GitHub documentation has general help on forking and cloning repos.

If you're not a member of the Dart organization, we recommend you create a fork of this repo under your own account, and then submit a PR from that fork.

Once you have a fork (or you're a Dart org member), choose one of the following submodule-cloning techniques:

Clone the repo and its submodule at the same time using the --recurse-submodules option:
```
git clone --recurse-submodules https://github.com/dart-lang/site-www.git
```
If you've already cloned the repo without its submodule, then run this command from the root of the repository:
```
git submodule update --init --recursive
```

Note

At any time during development you can use the git submodule command to refresh submodules:

git pull && git submodule update --init --recursive

Preview changes locally

Before you continue setting up the site infrastructure, verify the correct versions of Dart and Node.js are set up and available by following the instructions in Get the prerequisites.

Optional: After cloning the repo and its submodules, create a branch for your changes:
```
git checkout -b <BRANCH_NAME>
```
From the root directory of the repository, fetch the site's Dart dependencies.
```
dart pub get
```
Install pnpm using your preferred installation method. pnpm is an alternative, efficient package manager for npm packages. If you already have pnpm, verify you have the latest stable version. We recommend using corepack to install and manage pnpm versions, since it is bundled with most installations of Node.

If you haven't used corepack before, you'll need to first enable it with corepack enable. Then, to install the correct pnpm version, from the root directory of the repository, run corepack install:
```
corepack enable
corepack install
```
Once you have pnpm installed and setup, fetch the site's npm dependencies using pnpm install. We highly recommend you use pnpm, but you can also use npm.
```
pnpm install
```
From the root directory, run the dash_site tool to validate your setup and learn about the available commands.
```
./dash_site --help
```
From the root directory, serve the site locally.
```
./dash_site serve
```
This command generates and serves the site on a local port that's printed to your terminal.
View your changes in the browser by navigating to http://localhost:4000.

Note the port might be different if 4000 is taken.

If you want to check the raw, generated HTML output and structure, view the _site directory in a file explorer or an IDE.
Make your changes to the local repo.

The site should automatically rebuild on most changes, but if something doesn't update, exit the process and rerun the command. Improvements to this functionality are planned. Please open a new issue to track the issue if this occurs.
Commit your changes to the branch and submit your PR.

If your change is large, or you'd like to test it, consider validating your changes.

Tip

To find additional commands that you can run, run ./dash_site --help from the repository's root directory.

Update code samples

If your PR changes Dart code within a page, you'll probably need to change the code in two places:

In a .md file for the page.
In a .dart file under the /examples directory.

For example, say you want to change the following code in the Variables documentation:

<?code-excerpt "misc/lib/language_tour/variables.dart (var-decl)"?>
```dart
var name = 'Bob';
```

Besides editing /src/content/language/variables.md (which you can find by clicking the GitHub icon at the top right of the page), you'll also need to edit the var-decl region of /examples/misc/lib/language_tour/variables.dart.

If you create a PR but forget to edit the Dart file, or if your changes don't analyze/test cleanly, the GitHub Actions CI build will fail. Just update the PR, and GitHub Actions will run again.

A build that fails with the error Error: Some code excerpts needed to be updated! means that one or more code excerpts in the site Markdown files aren't identical to the code regions declared in the corresponding .dart files.

To resolve this error, from the root of the site-www directory, run ./dash_site refresh-excerpts.

To learn more about creating, editing, and using code excerpts, check out the excerpt updater package documentation.

Validate links and example code

If you've made changes to the code in the /examples or /tool directories, commit your work, then run the following command to verify it is up to date and matches the site standards.

./dash_site check-all

If this script reports any errors or warnings, then address those issues and rerun the command. If you have any issues, leave a comment on your issue or pull request, and we'll try our best to help you. You can also chat with us on the #hackers-devrel channel on the Flutter contributors Discord!

[Optional] Deploy to a staging site

A site maintainer can automatically stage submitted pull requests. If you'd like to first stage the site yourself, you can build a full version and upload it to Firebase.

If you don't already have a Firebase project,
- Navigate to the Firebase Console and create your own Firebase project (for example, dart-dev-staging).
- Head back to your local terminal and verify that you're logged in.
```
firebase login
```
- Ensure that your project exists and activate that project:
```
firebase projects:list
firebase use <your-project>
```
From the root directory of the repository, build the site:
```
./dash_site build
```
This builds the site and copies it to your local _site directory. If that directory previously existed, it will be replaced.
Deploy to your activated Firebase project's default hosting site:
```
firebase deploy --only hosting
```
Navigate to your PR on GitHub and include the link of the staged version. Do consider adding a reference to the commit you staged, so that reviewers know if any further changes have been made.

site-shared docs

To update site-shared docs, see the site-shared doc pages.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly