diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 00000000000..ee36accad32 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,38 @@ +# swc Archtecture + +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 + +swc uses proc macro extensively to reduce work. Please see links below to know what each macro do. + + - [enum_kind][] + - [string_enum][] + - [ast_node][] + +And some adhoc-macros are used. + + - [parser_macros][] + - [codegen_macros][] + +These macro breaks macro hygiene. + + +## Tests + +swc uses [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. + +Codegen tests ensures that generated code is equivalent to goldened reference files located at [tests/references](./emmascript/codegen/tests/references). + + + + +[enum_kind]:https://swc-project.github.io/rustdoc/enum_kind/derive.Kind.html +[string_enum]:https://swc-project.github.io/rustdoc/string_enum/derive.StringEnum.html +[ast_node]:https://swc-project.github.io/rustdoc/ast_node/index.html +[parser_macros]:https://swc-project.github.io/rustdoc/swc_ecma_parser_macros/index.html +[codegen_macros]:https://swc-project.github.io/rustdoc/swc_ecma_codegen_macros/index.html +[test262]:https://github.com/tc39/test262 \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000000..ac082ff162d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,150 @@ +# 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. + + + +## Code of Conduct + +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 +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. + +## Feature requests + +Please feel free to open a issue or to send a pr. + +## Working on issues + +If you're looking for somewhere to start, check out the [E-easy][E-Easy] and +[E-mentor][E-mentor] tags. + +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. + +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 +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 +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. + +Your basic steps to get going: + +* Fork swc and create a branch from master for the issue you are working on. +* 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 +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. +* 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. + + +## Pull requests + +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]. + +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 +commits to your branch to tackle these problems. + +The reviewer might point out changes deemed necessary. Please add them as +extra commits; this ensures that the reviewer can see what has changed since +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. + +## Contributing to the documentation + +TODO + +## Issue Triage + +Sometimes an issue will stay open, even though the bug has been fixed. And +sometimes, the original bug may go stale because something has changed in the +meantime. + +It can be helpful to go through older bug reports and make sure that they are +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 +adding labels to triage issues: + +* Yellow, **A**-prefixed labels state which **area** of the project an issue + relates to. + +* Magenta, **B**-prefixed labels identify bugs which are **blockers**. + +* Red, **C**-prefixed labels represent the **category** of an issue. + In particular, **C-feature-request** marks *proposals* for new features. If + 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 such issue. + +* Green, **E**-prefixed labels explain the level of **experience** or + **effort** necessary to fix the issue. [**E-mentor**][E-mentor] issues also + have some instructions on how to get started. + +* Purple gray, **O**-prefixed labels are the **operating system** or platform + that this issue is specific to. + +* Orange, **P**-prefixed labels indicate a bug's **priority**. + +* Ligth 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 +[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 +[gitter]: https://gitter.im/swcproject/Lobby +[`tesitng/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 \ No newline at end of file diff --git a/macros/ast_node/src/lib.rs b/macros/ast_node/src/lib.rs index 51b962c6cc1..eb81ca56d54 100644 --- a/macros/ast_node/src/lib.rs +++ b/macros/ast_node/src/lib.rs @@ -17,6 +17,15 @@ mod from_variant; mod spanned; mod visit; +/// Implements `FoldWith` and `VisitWith`. +/// +/// ## Attributes +/// `#[fold(ignore)]` +/// Skip a field. +/// +/// `#[fold(bound)]` +/// Add bound to the generated impl block. +/// Generic fields typically requires this attribute. #[proc_macro_derive(Fold, attributes(fold))] pub fn derive_fold(input: proc_macro::TokenStream) -> proc_macro::TokenStream { let input = parse::(input).expect("failed to parse input as DeriveInput");