Want to contribute? Great! First, read this page.
- Before You Contribute
- Development Dependencies
- Writing Code
Before You Contribute
Before we can use your code, you must sign the Google Individual Contributor License Agreement (CLA), which you can do online. The CLA is necessary mainly because you own the copyright to your changes, even after your contribution becomes part of our codebase, so we need your permission to use and distribute your code. We also need to be sure of various other things—for instance that you'll tell us if you know that your code infringes on other people's patents. You don't have to sign the CLA until after you've submitted your code for review and a member has approved it, but you must do it before we can put your code into our codebase.
Before you start working on a larger contribution, you should get in touch with us first through the issue tracker with your idea so that we can help out and possibly guide you. Coordinating up front makes it much easier to avoid frustration later on.
The Small Print
Contributions made by corporations are covered by a different agreement than the one above, the Software Grant and Corporate Contributor License Agreement.
Install the Dart SDK. If you download an archive manually rather than using an installer, make sure the SDK's
bindirectory is on your
In this repository, run
pub get. This will install all of the Dart dependencies.
Install Node.js. This is only necessary if you're making changes to Dart Sass's Node API.
Dart Sass follows the standard Dart style guide wherever possible, including using the Dart formatter on all code. We also try to have no Dart analyzer warnings or hints, although if one sneaks in for a few revisions that's not a big deal.
Before you send a pull request, we recommend you run the following steps:
pub run grinderwill reformat your code using the Dart formatter to make sure it's nice and neat, and run the synchronizer on asynchronous files.
dartanalyzer lib testwill run Dart's static analyzer to ensure that there aren't any obvious bugs in your code. If you're using a Dart-enabled IDE, you can also just check that there aren't any warnings in there.
pub run test -x nodewill run the tests for the Dart VM API. These are a good sanity check, but they aren't comprehensive; Travis CI will also run Node.js API tests and Sass language tests, all of which must pass before your pull request is merged. See Changing the Language and Changing the Node API for more details.
Changing the Language
If you're making a change to the Sass language, either to fix a bug or add a feature, you'll need to write tests in the sass-spec repository. This repository contains language tests that are shared among the main Sass implementations. Any new feature should be thoroughly tested there, and any bug should have a regression test added.
To create a new spec:
# Replace $USER with your GitHub username. git clone https://github.com/$USER/sass-spec cd sass-spec bundle install
For each test case you want to add:
Create a directory within
sass-spec/spec/for your test. Don't worry too much about finding exactly the right place, we'll sort that out during code review.
input.sassfile that exercises your language change.
If you're testing successful output, create an
expected_output.cssfile with the output that should be produced. If you're testing an error, instead create an
errorfile with the expected error message.
If you're adding a new language feature, it probably won't be supported by Ruby Sass or LibSass yet. You can indicate this and keep tests passing by adding an
options.ymlfile like this to the directory containing your tests:
--- :todo: - ruby-sass - libsass
If you're fixing a bug, you'll only need to do this if the bug also appears in other Sass implementations.
Make sure all the language tests, including the new ones, are passing by running this within
# Replace .. with the path to dart-sass if it's not the parent directory. bundle exec sass-spec.rb --dart ..
You can also run specs within a single directory:
bundle exec sass-spec.rb --dart .. spec/my/new/feature
If you pass the
sass-spec.rbwill stop each time a spec fails and ask you what to do about the failure.
Once you've added specs and they're passing for Dart Sass, create a pull request for sass-spec with
[skip dart-sass]at the end of the message. This tells sass-spec not to run tests against the old version of Dart Sass, since it doesn't have your changes yet.
Finally, create a pull request for Dart Sass with a link to the sass-spec pull request at the end of the message. This tells Dart Sass to test against your new sass-spec tests.
Changing the Node API
Most of Dart Sass's code is shared between Dart and Node.js, but the API that's
exported by the
sass npm package is Node-specific. It's defined using
Dart's [JS interop package], and it's tested by compiling the Dart package to
JS and loading that JS using JS interop to best simulate the conditions under
which it will be used in the real world.
The tests for the Node API live in
test/node_api. Before running them, and any
time you make a change to Dart Sass, run
pub run grinder before-test to
you've only changed the test code). To run Node tests, just run
pub run test -t node.
Dart Sass supports two modes of operation: synchronous (
compileString()), which requires all importers and custom functions to be
synchronous themselves, and asynchronous (
compileStringAsync()), which allows importers and custom functions to be
asynchronous. These modes use essentially identical logic, but because Dart
represents synchronous and asynchronous computations in fundamentally different
ways they can't share code.
To avoid colossal amounts of duplicated code, we have a few files that are
written in an asynchronous style originally and then compiled to their
synchronous equivalents using
tool/synchronize.dart. In particular:
lib/src/visitor/async_evaluate.dartis compiled to
lib/src/async_environment.dartis compiled to
When contributing code to these files, you should make manual changes only to
the asynchronous versions and run
pub run grinder to compile them to their
Note that the
lib/src/callable/built_in.dart files are not automatically synchronized;
they're so small and would require so many special cases that they're not worth
All files in the project must start with the following header.
// Copyright (c) 2018, the Dart project authors. Please see the AUTHORS file // for details. All rights reserved. Use of this source code is governed by a // BSD-style license that can be found in the LICENSE file.