Skip to content

Commit 5e7322b

Browse files
vrn-snaatxe
andauthored
Add a simple CONTRIBUTING.md file (#443)
[Rendered](https://github.com/luau-lang/lute/blob/vrn-sn/contributing-md/CONTRIBUTING.md). Feel free to commit to this branch directly. --------- Co-authored-by: ariel <arielweiss@roblox.com>
1 parent 1934ced commit 5e7322b

File tree

1 file changed

+65
-0
lines changed

1 file changed

+65
-0
lines changed

CONTRIBUTING.md

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Contributing to Lute
2+
3+
## Getting Started
4+
5+
First off, thank you for your interest in contributing to Lute!
6+
We're really excited about building a powerful standalone runtime for Luau, and we're glad that you are too!
7+
Whether you're fixing bugs, improving our documentation, or posting feature requests, we value your contributions!
8+
If you're interested in contributing code in particular, please continue reading this document and
9+
check out the [open issues](https://github.com/luau-lang/lute/issues) on our issue tracker for possible avenues to contribute!
10+
11+
## Ways to Contribute
12+
13+
- **Bug Reports:** Please open a [GitHub Issue](https://github.com/luau-lang/lute/issues/new) with a clear description, label, and reproduction steps.
14+
- **Feature Requests:** Open an issue with your idea and rationale.
15+
- **Code Contributions:** Fork this repository, create a branch, and submit a PR (see "Code Guidelines" below).
16+
17+
## Repository Structure
18+
19+
Lute as a project is organized to use [GitHub](https://github.com/luau-lang/lute) for issue tracking, project milestones, managing contributions, and so forth.
20+
Lute's [documentation site](https://luau-lang.github.io/lute) is also built from this repository, and accepts pull requests just like any other code does.
21+
22+
Navigating the repository benefits from knowing its structure, namely:
23+
- Source code lives in the [`/lute/`](./lute) directory,
24+
- type definitions are in [`/definitions/`](./definitions),
25+
- user-facing documentation is defined in [`/docs/`](./docs),
26+
- supporting tooling for working on lute is provided in [`/tools/`](./tools), and finally,
27+
- tests can be found in the [`/tests/`](./tests/) directory.
28+
29+
As a codebase, Lute consists of three components:
30+
1. The runtime itself, written in C++, defined in various modules under `/lute/` and accessible from Luau scripts via `require("@lute/module")`.
31+
These runtime libraries provide core functionality that extends the expressivity of Luau itself, and allows programmers to write general-purpose programs at all.
32+
2. The standard library, written in Luau, defined under `/lute/std/libs` and _embedded into the Lute executable_.
33+
The standard library provides a general interface for programming in Luau, one that we strive to make as delightful as it can be.
34+
It includes both wrappers of runtime functionality that allow runtime authors to support cross-runtime code, as well as
35+
general Luau libraries that improve the developer experience and increase developer productivity on new projects.
36+
3. batteries, written in Luau, defined in various modules under `/batteries/` which are not included in any formal distribution of Lute.
37+
A goal of Lute as a project is to build the foundations for a healthy open source ecosystem for Luau, and achieving that means building
38+
core developer tooling like _a package manager_. In the mean time, we need to write some Luau code to help us build the future, and we
39+
need a place for it to live. batteries are exactly that! Useful Luau code that should run everywhere, and that we can use to build our tooling.
40+
Once Luau has a proper package manager built on Lute, batteries will be pulled out of the repository and made available as a separate package.
41+
42+
## Code Guidelines
43+
44+
In the interest of having a consistent standard for code, we expect that incoming contributions will follow existing code styling.
45+
In support of this, we've provided appropriate configuration for autoformatter tools to help enforce this.
46+
For C++ code, we provide a `.clang-format` file; please make sure to format your code before opening a PR.
47+
All Luau scripts should be formatted with [StyLua](https://github.com/JohnnyMorganz/StyLua).
48+
49+
There are some additional style considerations that we do not have automated enforcement for today, but that we will address in reviews:
50+
51+
1. All Luau APIs exposed publically by Lute in both the runtime and the standard library must have identifiers written in `luacase`.
52+
This means module names, function names, table fields, exported types, etc. should be written in all lowercase, and should be named ideally with
53+
one or two words succinctly. We know this style is not everyone's favorite, and we do not advocate for external software to use it, but we would like
54+
to retain consistency with Luau's builtin library which inherits this convention from Lua.
55+
2. All other Luau code, including the internals of those Luau APIs, should be written using `camelCase` for identifiers and table fields, and `PascalCase` for type names.
56+
3. Every functionality change should come with tests that express the desired behavior of the code being added.
57+
4. Tests should be placed along side existing tests, and use the appropriate testing tools provided for Lute.
58+
C++ code should be tested using `doctest` and linked into a test executable.
59+
Luau code should be tested using Lute's testing framework, and should be written in a `.test.luau` file.
60+
5. Small, incremental contributions are always preferred over sweeping changes. You should expect that any large sweeping change will be rejected summarily without review.
61+
If you're interested in working on something that _requires_ such a change, you should open an issue first to discuss the idea and get buy-in from the team.
62+
63+
## Licensing
64+
65+
By providing code in an issue or opening a pull request, you agree to license that code under the MIT License, and indicate that you have the legal right to do so.

0 commit comments

Comments
 (0)