Add CONTRIBUTING.md and replace README.md

Also add SVG logo to docs/

CONTRIBUTING.md

@@ -0,0 +1,56 @@
+Thanks for deciding to contribute to Luau! These guidelines will try to help make the process painless and efficient.
+
+## Questions
+
+If you have a question regarding the language usage/implementation, please [use GitHub discussions](https://github.com/Roblox/luau/discussions).
+Some questions just need answers, but it's nice to keep them for future reference in case other people want to know the same thing.
+Some questions help improve the language, implementation or documentation by inspiring future changes.
+
+## Documentation
+
+This repository hosts the language documentation in addition to implementation, which is accessible on https://luau-lang.org.
+Changes to this documentation that improve clarity, fix grammatical issues, explain aspects that haven't been explained before and the like are warmly welcomed.
+
+Please feel free to [create a pull request](https://help.github.com/articles/about-pull-requests/) to improve our documentation. Note that at this point the documentation is English-only.
+
+## Bugs
+
+If the language implementation doesn't compile on your system, compiles with warnings, doesn't seem to run correctly for your code or if anything else is amiss, please [open a GitHub issue](https://github.com/Roblox/luau/issues/new).
+It helps if you note the Git revision issue happens in, the version of your compiler for compilation issues, and a reproduction case for runtime bugs.
+
+Of course, feel free to [create a pull request](https://help.github.com/articles/about-pull-requests/) to fix the bug yourself.
+
+## Features
+
+If you're thinking of adding a new feature to the language, library, analysis tools, etc., please *don't* start by submitting a pull request.
+Luau team has internal priorities and a roadmap that may or may not align with specific features, so before starting to work on a feature please submit an issue describing the missing feature that you'd like to add.
+
+For features that result in observable change of language syntax or semantics, you'd need to [create an RFC](https://github.com/Roblox/luau/blob/master/rfcs/README.md) to make sure that the feature is needed and well designed.
+Similarly to the above, please create an issue first so that we can see if we should go through with an RFC process.
+
+Finally, please note that Luau tries to carry a minimal feature set. All features must be evaluated not just for the benefits that they provide, but also for the downsides/costs in terms of language simplicity, maintainability, cross-feature interaction etc.
+As such, feature requests may not be accepted, or may get to an RFC stage and get rejected there - don't expect Luau to gain a feature just because another programming language has it.
+
+## Code style
+
+Contributions to this project are expected to follow the existing code style.
+`.clang-format` file mostly defines syntactic styling rules (you can run `make format` to format the code accordingly).
+
+As for naming conventions, most Luau components use `lowerCamelCase` for variables and functions, `UpperCamelCase` for types and enums, `kCamelCase` for global constants and `SCARY_CASE` for macros.
+
+Within the VM component, the code style is different - we expect `lua_` or `luaX_` prefix for functions that are public or used across different VM files, camel case isn't used and macros are often using lowercase.
+
+## Testing
+
+All pull requests will run through a continuous integration pipeline using GitHub Actions that will run the built-in unit tests and integration tests on Windows, macOS and Linux.
+You can run the tests yourself using `make test` or using `cmake` to build `Luau.UnitTest` and `Luau.Conformance` and run them.
+
+When making code changes please try to make sure they are covered by an existing test or add a new test accordingly.
+
+## Feature flags
+
+For large bug fixes or features that apply to the Luau components and not just the CLI tools, we may ask that you introduce a feature flag to gate your changes. The feature flags use `LUAU_FASTFLAG` macro family defined in `Luau/Common.h` and allow us to ensure that the change can be safely shipped, enabled, and rolled back on the Roblox platform when the change makes it into our production codebase. The tests run the code with flags in their default state and enabled state as well to ensure correctness.
+
+## Licensing
+
+By contributing changes to this repository, you license your contribution under the MIT License, and you agree that you have the right to license your contribution under those terms.

README.md

@@ -1,7 +1,60 @@
-Luau
+Luau ![CI](https://github.com/Roblox/luau/workflows/build/badge.svg)
 ====
 
-Luau is a fast, small, safe, gradually typed embeddable scripting language derived from Lua. It is used by Roblox game developers to write game code, as well as by Roblox engineers to implement large parts of the user-facing application code as well as portions of the editor (Roblox Studio) as plugins.
+Luau (lowercase u, /ˈlu.aʊ/) is a fast, small, safe, gradually typed embeddable scripting language derived from [Lua](https://lua.org).
 
-This repository hosts documentation for the language as well as satellite materials, and can be viewed at https://luau-lang.org/
+It is designed to be backwards compatible with Lua 5.1, as well as incorporating [some features](https://luau-lang.org/compatibility) from future Lua releases, but also expands the feature set (most notably with type annotations). Luau is largely implemented from scratch, with the language runtime being a very heavily modified version of Lua 5.1 runtime, with completely rewritten interpreter and other [performance innovations](https://luau-lang.org/performance). The runtime mostly preserves Lua 5.1 API, so existing bindings should be more or less compatible with a few caveats.
 
+Luau is used by Roblox game developers to write game code, as well as by Roblox engineers to implement large parts of the user-facing application code as well as portions of the editor (Roblox Studio) as plugins. Roblox chose to open-source Luau to foster collaboration within the Roblox community as well as to allow other companies and communities to benefit from the ongoing language and runtime innovation.
+
+This repository hosts source code for the language implementation and associated tooling, documentation for the language as well as RFCs and other materials. The documentation portion of this repository can be viewed at https://luau-lang.org/
+
+# Usage
+
+Luau is an embeddable language, but it also comes with two command-line tools by default, `luau` and `luau-analyze`.
+
+`luau` is a command-line REPL and can also run input files. Note that REPL runs in a sandboxed environment and as such doesn't have access to the underlying file system except for ability to `require` modules.
+
+`luau-analyze` is a command-line type checker and linter; given a set of input files, it produces errors/warnings according to the file configuration, which can be customized by using `--!` comments in the files or [`.luaurc`](https://github.com/Roblox/luau/blob/master/rfcs/config-luaurc.md) files. For details please refer to [type checking]( https://luau-lang.org/typecheck) and [linting](https://luau-lang.org/lint) documentation.
+
+The easiest way to get the command-line binaries is to use [artifact uploads](https://github.com/Roblox/luau/actions/workflows/release.yml) that are available for every commit to master.
+
+# Building
+
+To build Luau tools or tests yourself, you can use CMake on all platforms, or alternatively make (on Linux/macOS). For example:
+
+```sh
+mkdir cmake && cd cmake
+cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo
+cmake --build . --target Luau.Repl.CLI Luau.Analyze.CLI --config RelWithDebInfo
+```
+
+To integrate Luau into your CMake application projects, at the minimum you'll need to depend on `Luau.Compiler` and `Luau.VM` projects. From there you need to create a new Luau state (using Lua 5.x API such as `lua_newstate`), compile source to bytecode and load it into the VM like this:
+
+```
+std::string bytecode = Luau::compile(source); // needs Luau/Compiler.h include
+if (luau_load(L, chunkname, bytecode.data(), bytecode.size()) == 0)
+    return 1; /* return chunk main function */
+```
+
+For more details about the use of host API you currently need to consult [Lua 5.x API](https://www.lua.org/manual/5.1/manual.html#3). Luau closely tracks that API but has a few deviations, such as the need to compile source separately (which is important to be able to deploy VM without a compiler), or lack of `__gc` support (use `lua_newuserdatadtor` instead).
+
+To gain advantage of many performance improvements it's highly recommended to use `safeenv` feature, which sandboxes individual scripts' global tables from each other as well as protects builtin libraries from monkey-patching. For this to work you need to call `luaL_sandbox` for the global state and `luaL_sandboxthread` for each new script's execution thread.
+
+# Testing
+
+Luau has an internal test suite; in CMake builds it is split into two targets, `Luau.UnitTest` (for bytecode compiler and type checker/linter tests) and `Luau.Conformance` (for VM tests). The unit tests are written in C++, whereas the conformance tests are largerly written in Luau (see `tests/conformance`).
+
+Makefile builds combine both into a single target and can be ran via `make test`.
+
+# Dependencies
+
+Luau uses C++ as its implementation language. The runtime requires C++11, whereas the compiler and analysis components require C++17. It should build without issues using Microsoft Visual Studio 2017 or later, or gcc-7 or clang-7 or later.
+
+Other than the STL/CRT, Luau library components don't have external dependencies. The test suite depends on [doctest](https://github.com/onqtam/doctest) testing framework, and the REPL command-line depends on [cpp-linenoise](https://github.com/yhirose/cpp-linenoise).
+
+# License
+
+Luau implementation is distributed under the terms of [MIT License](https://github.com/Roblox/luau/blob/master/LICENSE.txt). It is based on Lua 5.x implementation that is MIT licensed as well.
+
+When Luau is integrated into external projects, we ask to honor the license agreement and include Luau attribution into the user-facing product documentation. The attribution using [Luau logo](https://github.com/Roblox/luau/blob/master/docs/logo.svg) is also encouraged.

docs/logo.svg

@@ -0,0 +1,5 @@
+<svg width="60" height="60" viewBox="0 0 60 60" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect x="15.8579" y="5.5051" width="40" height="40" transform="rotate(15 15.8579 5.5051)" fill="#00A2FF"/>
+<rect x="40.6438" y="17.3228" width="8" height="8" transform="rotate(15 40.6438 17.3228)" fill="white"/>
+<path d="M13.2989 39.8636L18.1804 41.1716L17.8828 42.2824L11.6359 40.6085L14.396 30.3078L15.7614 30.6737L13.2989 39.8636ZM23.8444 43.0684C23.1745 43.5309 22.3467 43.6301 21.361 43.366C20.5451 43.1474 19.9857 42.7447 19.6829 42.1581C19.386 41.568 19.3597 40.8077 19.604 39.8773L20.9385 34.8968L22.2473 35.2475L20.9223 40.1926C20.6114 41.3529 20.9276 42.0594 21.8709 42.3121C22.8707 42.5801 23.6356 42.3857 24.1654 41.7289L25.6573 36.1612L26.9661 36.5119L24.915 44.1666L23.6699 43.833L23.8444 43.0684ZM31.6359 45.9675C31.6009 45.7964 31.6116 45.5111 31.6681 45.1117C30.8903 45.5807 30.0793 45.7021 29.2351 45.4758C28.4805 45.2736 27.9171 44.8952 27.5451 44.3406C27.179 43.7825 27.0838 43.1756 27.2595 42.52C27.473 41.723 27.9404 41.186 28.6617 40.9091C29.3889 40.6288 30.302 40.6359 31.4009 40.9303L32.6743 41.2716L32.8355 40.6702C32.958 40.2127 32.9186 39.8129 32.7171 39.4708C32.5168 39.1239 32.1502 38.8791 31.6172 38.7363C31.1503 38.6112 30.7272 38.6242 30.3481 38.7753C29.9689 38.9265 29.7344 39.1695 29.6447 39.5044L28.3288 39.1518C28.4312 38.7697 28.6642 38.4379 29.0278 38.1562C29.3974 37.871 29.8411 37.6866 30.3589 37.6029C30.8814 37.5205 31.421 37.5539 31.9775 37.703C32.8595 37.9393 33.491 38.3461 33.8722 38.9234C34.2546 39.496 34.3516 40.1716 34.1632 40.9502L33.2192 44.4733C33.0309 45.1761 32.9707 45.759 33.0388 46.2221L33.0084 46.3353L31.6359 45.9675ZM29.7313 44.388C30.1416 44.498 30.5592 44.4961 30.9839 44.3824C31.4087 44.2688 31.7491 44.0643 32.0052 43.7689L32.426 42.1983L31.4002 41.9235C29.7966 41.4938 28.869 41.7482 28.6176 42.6868C28.5076 43.0971 28.5584 43.4545 28.7701 43.7589C28.9817 44.0633 29.3021 44.273 29.7313 44.388ZM39.7199 47.3223C39.0501 47.7848 38.2223 47.8839 37.2365 47.6198C36.4206 47.4012 35.8612 46.9986 35.5584 46.4119C35.2615 45.8218 35.2352 45.0616 35.4795 44.1312L36.814 39.1506L38.1228 39.5013L36.7978 44.4465C36.4869 45.6067 36.8031 46.3132 37.7464 46.566C38.7463 46.8339 39.5111 46.6395 40.0409 45.9827L41.5328 40.415L42.8416 40.7657L40.7905 48.4205L39.5454 48.0868L39.7199 47.3223Z" fill="white"/>
+</svg>