diff --git a/old_source/blog/037-rfc-embedded-protocol-2.md b/old_source/blog/037-rfc-embedded-protocol-2.md new file mode 100644 index 0000000..b5a2527 --- /dev/null +++ b/old_source/blog/037-rfc-embedded-protocol-2.md @@ -0,0 +1,76 @@ +--- +title: "Request for Comments: New Embedded Protocol" +author: Natalie Weizenbaum +date: 2023-05-19 16:00 PST +--- + +If you're not an author of a host package for the Embedded Sass Protocol, you +can skip this blog post—although if you're a big enough nerd, you may find it +interesting regardless! + +We're planning to make a number of breaking changes to the Embedded Sass +Protocol, and we want your feedback before we lock in the new way of doing +things. We intend to make a number of breaking changes all at once to keep the +total number of disruptions to a minimum. + +We're planning two major breaking changes: + +1. The Dart Sass embedded host will no longer be released as a separate + executable. It will now be bundled into the main Dart Sass executable, + accessible by running `sass --embedded`. + +2. Every packet in the embedded protocol now includes a compilation ID as part + of the packet structure, rather than declaring it in the protocol buffer + definitions. + +We're using this opportunity to also introduce three much smaller breaking +changes: + +1. The specification for the embedded protocol and the protocol buffer + definition have been moved to [the Sass language repository] so that they can + be updated at the same time as changes to the language and the JS API. + + [the Sass language repository]: https://github.com/sass/sass/blob/main/spec/embedded-protocol.md + +2. The embedded protocol now explicitly declares optional fields using the + protocol buffers language feature. This means that "default values" for + various fields are no longer considered to be unset. + +3. The `CompilationSuccess.loaded_urls` field has been moved to + `CompilationResult.loaded_urls` so that it's available even when a + compilation fails. This allows watcher implementations to know which files to + watch to redo a failed compilation. + +The repository-organization changes have already been made, but the changes to +the protocol itself are fully documented [in a proposal in the language +repository]. + +[in a proposal in the language repository]: https://github.com/sass/sass/blob/main/proposal/embedded-protocol-2.md + +## Combining Executables + +The primary benefit of folding Embedded Dart Sass into the main Dart Sass +executable is to provide embedded hosts an easy way to expose the standard Dart +Sass command-line API to users. Now every user who installs any embedded host +will have the full Dart Sass executable available to them at native Dart VM +speeds. + +This also helps simplify the Sass team's organization by reducing the number of +separate repositories and release processes we need to manage. + +## Wire-Level Compilation ID + +We're pulling the compilation ID out to the protocol level in order to provide +better concurrency, particularly on the side of the embedded compiler. Sass +compilations done by the embedded compiler don't share any state between one +another, which means that they could in theory be run in totally separate worker +threads. However, with the embedded protocol as it exists today, directing each +message to the correct worker thread requires parsing the entire message on the +main thread to determine which compilation it belongs to, then parsing it +_again_ in the worker thread to actually handle it. + +Making the compilation ID part of the protocol itself solves this issue. Each +endpoint can read the ID, look up the worker thread that's handling the +compilation, and pass the message on to that thread without parsing the rest of +the message. This makes concurrency both easier and more efficient, which will +help ensure that large compilations happen as fast as possible. diff --git a/package.json b/package.json index bcbba1c..53ec464 100644 --- a/package.json +++ b/package.json @@ -48,18 +48,18 @@ "@rollup/plugin-commonjs": "^25.0.0", "@rollup/plugin-inject": "^5.0.3", "@rollup/plugin-node-resolve": "^15.0.2", - "@rollup/plugin-terser": "^0.4.1", + "@rollup/plugin-terser": "^0.4.3", "@types/jquery": "^3.5.16", - "@types/jqueryui": "^1.12.16", + "@types/jqueryui": "^1.12.17", "@types/markdown-it": "^12.2.3", "@types/markdown-it-attrs": "^4.1.0", "@types/node": "^16", "@types/prismjs": "^1.26.0", - "@typescript-eslint/eslint-plugin": "^5.59.5", - "@typescript-eslint/parser": "^5.59.5", + "@typescript-eslint/eslint-plugin": "^5.59.6", + "@typescript-eslint/parser": "^5.59.6", "date-fns": "^2.30.0", "deep-equal": "^2.2.1", - "eslint": "^8.40.0", + "eslint": "^8.41.0", "eslint-config-prettier": "^8.8.0", "eslint-import-resolver-typescript": "^3.5.5", "eslint-plugin-import": "^2.27.5", @@ -77,10 +77,10 @@ "npm-run-all": "^4.1.5", "prettier": "^2.8.8", "prismjs": "^1.29.0", - "rollup": "^3.21.7", + "rollup": "^3.23.0", "sass": "^1.62.1", "semver-parser": "^4.1.4", - "stylelint": "^15.6.1", + "stylelint": "^15.6.2", "stylelint-config-standard-scss": "^9.0.0", "truncate-html": "^1.0.4", "ts-node": "^10.9.1", diff --git a/source/blog/037-rfc-embedded-protocol-2.md b/source/blog/037-rfc-embedded-protocol-2.md new file mode 100644 index 0000000..f902db4 --- /dev/null +++ b/source/blog/037-rfc-embedded-protocol-2.md @@ -0,0 +1,76 @@ +--- +title: "Request for Comments: New Embedded Protocol" +author: Natalie Weizenbaum +date: 2023-05-19 16:00:00 -8 +--- + +If you're not an author of a host package for the Embedded Sass Protocol, you +can skip this blog post—although if you're a big enough nerd, you may find it +interesting regardless! + +We're planning to make a number of breaking changes to the Embedded Sass +Protocol, and we want your feedback before we lock in the new way of doing +things. We intend to make a number of breaking changes all at once to keep the +total number of disruptions to a minimum. + +We're planning two major breaking changes: + +1. The Dart Sass embedded host will no longer be released as a separate + executable. It will now be bundled into the main Dart Sass executable, + accessible by running `sass --embedded`. + +2. Every packet in the embedded protocol now includes a compilation ID as part + of the packet structure, rather than declaring it in the protocol buffer + definitions. + +We're using this opportunity to also introduce three much smaller breaking +changes: + +1. The specification for the embedded protocol and the protocol buffer + definition have been moved to [the Sass language repository] so that they can + be updated at the same time as changes to the language and the JS API. + + [the Sass language repository]: https://github.com/sass/sass/blob/main/spec/embedded-protocol.md + +2. The embedded protocol now explicitly declares optional fields using the + protocol buffers language feature. This means that "default values" for + various fields are no longer considered to be unset. + +3. The `CompilationSuccess.loaded_urls` field has been moved to + `CompilationResult.loaded_urls` so that it's available even when a + compilation fails. This allows watcher implementations to know which files to + watch to redo a failed compilation. + +The repository-organization changes have already been made, but the changes to +the protocol itself are fully documented [in a proposal in the language +repository]. + +[in a proposal in the language repository]: https://github.com/sass/sass/blob/main/proposal/embedded-protocol-2.md + +## Combining Executables + +The primary benefit of folding Embedded Dart Sass into the main Dart Sass +executable is to provide embedded hosts an easy way to expose the standard Dart +Sass command-line API to users. Now every user who installs any embedded host +will have the full Dart Sass executable available to them at native Dart VM +speeds. + +This also helps simplify the Sass team's organization by reducing the number of +separate repositories and release processes we need to manage. + +## Wire-Level Compilation ID + +We're pulling the compilation ID out to the protocol level in order to provide +better concurrency, particularly on the side of the embedded compiler. Sass +compilations done by the embedded compiler don't share any state between one +another, which means that they could in theory be run in totally separate worker +threads. However, with the embedded protocol as it exists today, directing each +message to the correct worker thread requires parsing the entire message on the +main thread to determine which compilation it belongs to, then parsing it +_again_ in the worker thread to actually handle it. + +Making the compilation ID part of the protocol itself solves this issue. Each +endpoint can read the ID, look up the worker thread that's handling the +compilation, and pass the message on to that thread without parsing the rest of +the message. This makes concurrency both easier and more efficient, which will +help ensure that large compilations happen as fast as possible. diff --git a/source/documentation/index.md b/source/documentation/index.md index 5802dbe..727486f 100644 --- a/source/documentation/index.md +++ b/source/documentation/index.md @@ -29,7 +29,7 @@ introduction: > ## Older Versions This documentation is written for the most recent version of the Sass language. -If you're using [Dart Sass] <%= impl_version(:dart) %>, you'll have access to +If you're using [Dart Sass] {{ releases['dart-sass'].version }}, you'll have access to all the features described here. But if you're using an older version of Dart Sass or a deprecated Sass implementation like [LibSass] or [Ruby Sass], there may be some behavioral differences. diff --git a/source/documentation/syntax/comments.liquid b/source/documentation/syntax/comments.liquid index df12540..e5af630 100644 --- a/source/documentation/syntax/comments.liquid +++ b/source/documentation/syntax/comments.liquid @@ -25,9 +25,9 @@ By default, multi-line comments be stripped from the compiled CSS in [compressed mode][]. If a comment begins with `/*!`, though, it will always be included in the CSS output. -[statement]: structure#statements -[interpolation]: ../interpolation -[compressed mode]: ../cli/dart-sass#style +[statement]: ../structure#statements +[interpolation]: ../../interpolation +[compressed mode]: ../../cli/dart-sass#style {% endmarkdown %} {% codeExample 'scss-comment', , true, 'scss'%} @@ -64,7 +64,7 @@ stripped in compressed mode. Comments can also be used within [expressions][] in the indented syntax. In this case, they have exactly the same syntax as they do in SCSS. -[expressions]: structure#expressions +[expressions]: ../structure#expressions {% endmarkdown %} {% codeExample 'sass-comment', , true, 'sass'%} @@ -92,10 +92,10 @@ read by the [SassDoc][] tool, which uses them to generate beautiful documentation. Check out [the Susy grid engine][susy]'s documentation to see it in action! -[mixins]: ../at-rules/mixin -[functions]: ../at-rules/function -[variables]: ../variables -[placeholder selectors]: ../style-rules/placeholder-selectors +[mixins]: ../../at-rules/mixin +[functions]: ../../at-rules/function +[variables]: ../../variables +[placeholder selectors]: ../../style-rules/placeholder-selectors [SassDoc]: http://sassdoc.com [susy]: http://oddbird.net/susy/docs/index.html diff --git a/source/documentation/syntax/special-functions.liquid b/source/documentation/syntax/special-functions.liquid index 5614dea..69b6dc7 100644 --- a/source/documentation/syntax/special-functions.liquid +++ b/source/documentation/syntax/special-functions.liquid @@ -3,10 +3,10 @@ title: Special Functions introduction: > CSS defines many functions, and most of them work just fine with Sass’s normal function syntax. They’re parsed as function calls, resolved to [plain CSS - functions](../at-rules/function#plain-css-functions), and compiled as-is to + functions](../../at-rules/function#plain-css-functions), and compiled as-is to CSS. There are a few exceptions, though, which have special syntax that can’t - just be parsed as a [SassScript expression](structure#expressions). All - special function calls return [unquoted strings](../values/strings#unquoted). + just be parsed as a [SassScript expression](../structure#expressions). All + special function calls return [unquoted strings](../../values/strings#unquoted). table_of_contents: true complementary_content: |