From 3ebc5c6b6905d28769da6aefb48646a4ad6d023d Mon Sep 17 00:00:00 2001 From: Tim Neutkens Date: Mon, 15 Nov 2021 05:26:04 +0100 Subject: [PATCH] chore: Update markdown files to use "SWC" instead of "swc" (#2744) --- ARCHITECTURE.md | 64 +++++++++++------------ CONTRIBUTING.md | 67 +++++++++++-------------- README.md | 8 +-- crates/swc_babel_compat/README.md | 3 +- crates/swc_babel_compat/tests/README.md | 7 +-- crates/swc_bundler/README.md | 12 ++--- crates/swc_css_parser/README.md | 2 +- crates/swc_ecma_minifier/README.md | 2 +- crates/swc_plugin/README.md | 2 +- 9 files changed, 81 insertions(+), 86 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 36472d5fd752..01a9cbd5aa84 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,53 +1,54 @@ -# swc architecture +# SWC architecture -This document gives a high level overview of swc internals. You may find it useful if you want to contribute to swc or if you are interested in the inner workings of swc. +This document gives a high level overview of SWC internals. You may find it useful if you want to contribute to SWC or if you are interested in the inner workings of SWC. ## Macros -See [blog post about swc macros](https://swc.rs/blog/2020/01/04/pmutil#macros-built-with-pmutil). + + -swc uses proc macro extensively to reduce work. Please see links below to know what each macro do. +SWC uses proc macro extensively to reduce work. Please see links below to know what each macro do. -- [enum_kind][] -- [string_enum][] -- [ast_node][] +- [enum_kind][] +- [string_enum][] +- [ast_node][] And some adhoc-macros are used. -- [parser_macros][] -- [codegen_macros][] +- [parser_macros][] +- [codegen_macros][] These macro breaks macro hygiene. ## Structure -### `/atoms` +### [`/crates/swc_atoms`](crates/swc_atoms) -Handle string interning for the swc project. The crate depends on [string_cache](https://github.com/servo/string-cache) from servo. +Handle string interning for the SWC project. The crate depends on [string_cache](https://github.com/servo/string-cache) from servo. -### `/common` +### [`/crates/swc_common`](crates/swc_common) Contains code related to span, hygiene and error reporting. Also, it contains / re-exports codes for visitor pattern. `Visit` is non-mutating visitor, while `Fold` is a mutating visitor. -### `/ecmascript/ast` +### [`/crates/swc_ecma_ast`](crates/swc_ecma_ast) -Contains ast nodes for javascript and typescript. +Contains AST nodes for javascript and typescript. -### `/ecmascript/codegen` +### [`/crates/swc_ecma_codegen`](crates/swc_ecma_codegen) -Converts javascript ast into javascript code. +Converts javascript AST into javascript code. -### `/ecmascript/parser` +### [`/crates/swc_ecma_parser`](crates/swc_ecma_parser) Parses javascript and typescript -### `/ecmascript/transforms` +### [`/crates/swc_ecma_transforms_base`](crates/swc_ecma_transforms_base) Theres are three core transforms named `resolver`, `hygiene`, `fixer`. Other transforms depends on them. -#### `/ecmascript/transforms/src/resolver` +#### [`/crates/swc_ecma_transforms_base/src/resolver`](crates/swc_ecma_transforms_base/src/resolver) This pass resolves and marks all identifiers in the file. @@ -56,7 +57,7 @@ e.g. ```js let a = 1; { - let a = 1; + let a = 1; } ``` @@ -71,7 +72,7 @@ let a#0 = 1; where number after `#` denotes the hygiene id. If two identifiers have same symbol but different hygiene id, it's different. -#### `/ecmascript/transforms/src/hygiene` +#### [`/crates/swc_ecma_transforms_base/src/hygiene`](crates/swc_ecma_transforms_base/src/hygiene) Hygiene pass actually changes symbol of identifiers with same symbol but different hygiene id. @@ -87,13 +88,13 @@ becomes ```js let a = 1; { - let a1 = 2; + let a1 = 2; } ``` -#### `/ecmascript/transforms/src/fixer` +#### [`/crates/swc_ecma_transforms_base/src/fixer`](crates/swc_ecma_transforms_base/src/fixer) -Fixes borken ast. This allow us to simply fold types like `BinExpr` without caring about operator precedence. +Fixes broken AST. This allow us to simply fold types like `BinExpr` without caring about operator precedence. It means, @@ -105,7 +106,7 @@ let v = BinExpr { }; ``` -(other passes generates ast like this) +(other passes generates AST like this) is converted into @@ -123,9 +124,10 @@ and printed as (1 + 2) * 3; ``` -#### `/ecmascript/transforms/src/compat` + + ## Tests -swc uses [official ecmascript conformance test suite called test262][test262] for testing. +SWC uses the [official ecmascript conformance test suite called test262][test262] for testing. -Parser tests ensures that parsed result of test262/pass is identical with test262/pass-explicit. +Parser tests ensures that parsed result of `test262/pass` is identical with `test262/pass-explicit`. -Codegen tests ensures that generated code is equivalent to goldened reference files located at [tests/references](ecmascript/codegen/tests/references). +Codegen tests ensures that generated code is equivalent to golden fixture files located at [tests/references](crates/swc_ecma_codegen/tests). [enum_kind]: https://rustdoc.swc.rs/enum_kind/derive.Kind.html [string_enum]: https://rustdoc.swc.rs/string_enum/derive.StringEnum.html diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 47fbbe022671..88027064a0bf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,10 @@ -# Contributing to swc +# Contributing to SWC -Thank you for your interest in contributing to swc! Good places to start are this document, ARCHITECTURE.md, which describes the high-level structure of swc and E-easy bugs on the issue tracker. +Thank you for your interest in contributing to SWC! Good places to start are: + +- Reading this document +- Reading the high-level structure of SWC in [ARCHITECTURE.md](ARCHITECTURE.md) +- [E-easy][e-easy] labeled issues on the [issue tracker][issue-tracker] ## Code of Conduct @@ -8,30 +12,15 @@ All contributors are expected to follow our [Code of Conduct]. ## Bug reports -We can't fix what we don't know about, so please report problems liberally. This +We can't fix what we don't know about, so please report problems. This includes problems with understanding the documentation, unhelpful error messages, and unexpected behavior. -Opening an issue is as easy as following [this link][new-issues] and filling out -the fields. Here's a template that you can use to file an issue, though it's not -necessary to use it exactly: - - - - I tried this: - - I expected to see this happen: - - Instead, this happened: - - I'm using - -All three components are important: what you did, what you expected, what -happened instead. Please use https://gist.github.com/ if your examples run long. +You can open a new issue by following [this link][new-issues] and choosing one of the issue templates. ## Feature requests -Please feel free to open an issue or to send a pr. +Please feel free to open an issue using the [feature request template][new-issues]. ## Working on issues @@ -40,8 +29,8 @@ If you're looking for somewhere to start, check out the [E-easy][e-easy] and Feel free to ask for guidelines on how to tackle a problem on [gitter][] or open a [new issue][new-issues]. This is especially important if you want to add new -features to swc or make large changes to the already existing code-base. -swc's core developers will do their best to provide help. +features to SWC or make large changes to the already existing code-base. +The SWC core developers will do their best to provide help. If you start working on an already-filed issue, post a comment on this issue to let people know that somebody is working it. Feel free to ask for comments if @@ -50,30 +39,29 @@ you are unsure about the solution you would like to submit. We use the "fork and pull" model [described here][development-models], where contributors push changes to their personal fork and create pull requests to bring those changes into the source repository. This process is partly -automated: Pull requests are made against swc's master-branch, tested and +automated: Pull requests are made against SWC's repository, tested and reviewed. Once a change is approved to be merged, a friendly bot merges the changes into an internal branch, runs the full test-suite on that branch -and only then merges into master. This ensures that swc's master branch -passes the test-suite at all times. +and only then merges into master. This ensures that SWC passes the test-suite at all times. -Your basic steps to get going: +Steps to get started: -- Fork swc and create a branch from master for the issue you are working on. +- Fork SWC and create a branch from master for the issue you are working on. - Make sure you have the `make` utility installed, along with Rust and C/C++ compilers. - Please adhere to the code style that you see around the location you are working on. - [Commit as you go][githelp]. - Include tests that cover all non-trivial code. The existing tests - in `test/` provide templates on how to test swc's behavior in a + in `test/` provide templates on how to test SWC's behavior in a sandbox-environment. The internal crate `testing` provides a vast amount of helpers to minimize boilerplate. See [`testing/lib.rs`] for an introduction to writing tests. -- Make sure `cargo test` passes. +- Run `cargo test` and make sure that it passes. - All code changes are expected to comply with the formatting suggested by `rustfmt`. You can use `rustup component add --toolchain nightly rustfmt-preview` to install `rustfmt` and use `rustfmt +nightly --unstable-features --skip-children` on the changed files to automatically format your code. -- Push your commits to GitHub and create a pull request against swc's `master` branch. +- Push your commits to GitHub and create a pull request against the `swc-project/swc` `master` branch. ## Getting your development environment set up @@ -111,12 +99,12 @@ After cloning the project there are a few steps required to get the project runn ## Pull requests -After the pull request is made, one of the swc project developers will review your code. +After the pull request is made, one of the SWC project developers will review your code. The review-process will make sure that the proposed changes are sound. Please give the assigned reviewer sufficient time, especially during weekends. -If you don't get a reply, you may poke the core developers on [gitter]. +If you don't get a reply, you may ping the core developers on [gitter]. -A merge of swc's master-branch and your changes is immediately queued +A merge of SWC's master-branch and your changes is immediately queued to be tested after the pull request is made. In case unforeseen problems are discovered during this step (e.g. a failure on a platform you originally did not develop on), you may ask for guidance. Push additional @@ -128,11 +116,13 @@ the code was previously reviewed. Large or tricky changes may require several passes of review and changes. Once the reviewer approves your pull request, a friendly bot picks it up -and merges it into swc's `master` branch. +and merges it into the SWC `master` branch. ## Contributing to the documentation -TODO +The SWC documentation can be found at [`swc-project/website`](https://github.com/swc-project/website/tree/master/pages/docs). + +At the bottom of each page on [swc.rs](https://swc.rs) there is a `Edit this page on GitHub` button that immediately links to the right page to edit. ## Issue Triage @@ -145,7 +135,7 @@ still valid. Load up an older issue, double check that it's still true, and leave a comment letting us know if it is or is not. The [least recently updated sort][lru] is good for finding issues like this. -Contributors with sufficient permissions on the Rust-repository can help by +Contributors with sufficient permissions on the SWC repository can help by adding labels to triage issues: - Yellow, **A**-prefixed labels state which **area** of the project an issue @@ -158,7 +148,7 @@ adding labels to triage issues: an issue is **C-feature-request**, but is not **Feature accepted**, then it was not thoroughly discussed, and might need some additional design or perhaps should be implemented as an external subcommand first. Ping - @swc-projcet/swc if you want to send a PR for an such issue. + `@swc-project/swc` if you want to send a PR for an such issue. - Green, **E**-prefixed labels explain the level of **experience** or **effort** necessary to fix the issue. [**E-mentor**][e-mentor] issues also @@ -171,7 +161,7 @@ adding labels to triage issues: - Light orange, **L**-prefixed labels indicate language related to the bug. [gist]: https://gist.github.com/ -[new-issues]: https://github.com/swc-project/swc/issues/new +[new-issues]: https://github.com/swc-project/swc/issues/new/choose [e-easy]: https://github.com/swc-project/swc/labels/E-easy [e-mentor]: https://github.com/swc-project/swc/labels/E-mentor [code of conduct]: https://www.rust-lang.org/conduct.html @@ -179,3 +169,4 @@ adding labels to triage issues: [`testing/lib.rs`]: https://github.com/swc-project/swc/blob/master/testing/src/lib.rs [irlo]: https://internals.rust-lang.org/ [subcommands]: https://doc.rust-lang.org/cargo/reference/external-tools.html#custom-subcommands +[issue-tracker]: https://github.com/swc-project/swc/issues diff --git a/README.md b/README.md index 0d99e86a5866..b5069d324e5c 100644 --- a/README.md +++ b/README.md @@ -22,9 +22,9 @@

-swc (stands for `speedy web compiler`) is a super-fast typescript / javascript compiler written in rust. It's a library for rust and javascript at the same time. If you are using swc from rust, see [rustdoc](https://rustdoc.swc.rs/swc/) and for most users, your entrypoint for using library will be [parser](https://rustdoc.swc.rs/swc_ecma_parser/). +SWC (stands for `Speedy Web Compiler`) is a super-fast TypeScript / JavaScript compiler written in Rust. It's a library for Rust and JavaScript at the same time. If you are using SWC from Rust, see [rustdoc](https://rustdoc.swc.rs/swc/) and for most users, your entry point for using the library will be [parser](https://rustdoc.swc.rs/swc_ecma_parser/). -If you are using swc from javascript, please refer to [docs on the website](https://swc.rs/docs/installation/). +If you are using SWC from JavaScript, please refer to [docs on the website](https://swc.rs/docs/installation/). # Documentation @@ -55,7 +55,7 @@ Please see [benchmark results](https://swc.rs/docs/benchmark-transform) on the w

-swc is a community-driven project, and is maintained by a group of [volunteers](https://opencollective.com/swc#team). If you'd like to help support the future of the project, please consider: +SWC is a community-driven project, and is maintained by a group of [volunteers](https://opencollective.com/swc#team). If you'd like to help support the future of the project, please consider: - Giving developer time on the project. (Message us on [Discord](https://discord.gg/GnHbXTdZz6) (preferred) or [Github discussions](https://github.com/swc-project/swc/discussions) for guidance!) - Giving funds by becoming a sponsor (see https://opencollective.com/swc)! @@ -67,7 +67,7 @@ documentation useful ([ARCHITECTURE.md](ARCHITECTURE.md)). ## License -swc is primarily distributed under the terms of both the MIT license +SWC is primarily distributed under the terms of both the MIT license and the Apache License (Version 2.0). See LICENSE-APACHE and LICENSE-MIT for details. diff --git a/crates/swc_babel_compat/README.md b/crates/swc_babel_compat/README.md index 546ae0164b6f..df6ff3bdefb6 100644 --- a/crates/swc_babel_compat/README.md +++ b/crates/swc_babel_compat/README.md @@ -1,6 +1,7 @@ -Convert swc AST to Babel AST. +Convert SWC AST to Babel AST. ## Testing + To run tests ```bash diff --git a/crates/swc_babel_compat/tests/README.md b/crates/swc_babel_compat/tests/README.md index 8fe54f6cdc77..c53446f34d68 100644 --- a/crates/swc_babel_compat/tests/README.md +++ b/crates/swc_babel_compat/tests/README.md @@ -1,5 +1,6 @@ ## How tests work -The babel-compat tests are mostly written as fixtures, similar to the [@babel/parser tests](https://github.com/babel/babel/tree/main/packages/babel-parser/test/fixtures). The `src/convert.rs` test runner looks in the `fixtures/` directory for input and expected output files. Input files are parsed into an swc AST and converted to a Babel AST in Rust. Output files are parsed directly into a Babel AST. The two ASTs are then compared, with any differences causing the test to fail. + +The babel-compat tests are mostly written as fixtures, similar to the [@babel/parser tests](https://github.com/babel/babel/tree/main/packages/babel-parser/test/fixtures). The `src/convert.rs` test runner looks in the `fixtures/` directory for input and expected output files. Input files are parsed into an SWC AST and converted to a Babel AST in Rust. Output files are parsed directly into a Babel AST. The two ASTs are then compared, with any differences causing the test to fail. ## How to write a test @@ -24,6 +25,6 @@ node babelgen.js fixtures/my-test/input.js > fixtures/my-test/output.json This happens a lot with `None` and `Some(false)`. You'll probably want to add a normalizer function to the Normalizer visitor in `src/normalize/mod.rs`. ## Other random utlities -- `swcgen.js`: Prints the swc AST as JSON. -- `compare.sh`: prints the Babel and swc ASTs side-by-side. +- `swcgen.js`: Prints the SWC AST as JSON. +- `compare.sh`: prints the Babel and SWC ASTs side-by-side. diff --git a/crates/swc_bundler/README.md b/crates/swc_bundler/README.md index f9b0b73a98cc..63ec86d792bf 100644 --- a/crates/swc_bundler/README.md +++ b/crates/swc_bundler/README.md @@ -1,13 +1,13 @@ # swc_bundler -Bundler for the swc project. +Bundler for the SWC project. ## Features -- Clean merging (generated code is easy to optimize) -- Parallel file loading -- Tree shaking -- Common js support (aka `require`) -- Circular imports +- Clean merging (generated code is easy to optimize) +- Parallel file loading +- Tree shaking +- Common js support (aka `require`) +- Circular imports Tests live at `/spack`. diff --git a/crates/swc_css_parser/README.md b/crates/swc_css_parser/README.md index d2634ae84450..d5eca05587d9 100644 --- a/crates/swc_css_parser/README.md +++ b/crates/swc_css_parser/README.md @@ -1,6 +1,6 @@ # swc_css_parser -CSS parser for [the swc project](https://swc.rs) +CSS parser for [the SWC project](https://swc.rs) # Structure diff --git a/crates/swc_ecma_minifier/README.md b/crates/swc_ecma_minifier/README.md index 7d5c29a394e6..4b998e1f74cf 100644 --- a/crates/swc_ecma_minifier/README.md +++ b/crates/swc_ecma_minifier/README.md @@ -1,6 +1,6 @@ # Minifier -EcmaScript minifier for the swc project. This is basically a port of terser. +EcmaScript minifier for the SWC project. This is basically a port of terser. # Note diff --git a/crates/swc_plugin/README.md b/crates/swc_plugin/README.md index bddfadc24e1c..731ad459aacb 100644 --- a/crates/swc_plugin/README.md +++ b/crates/swc_plugin/README.md @@ -1,3 +1,3 @@ # swc_plugin -Base runtime for swc plugins, written in rust. +Base runtime for SWC plugins, written in rust.