nandi.uk
Fork of daniellemaywood.uk/gleam — Wasm codegen work
4.5 kB
130 lines
1<!--
2 SPDX-License-Identifier: Apache-2.0
3 SPDX-FileCopyrightText: 2024 The Gleam contributors
4-->
5
6# Contributing to Gleam
7
8Thanks for contributing to Gleam!
9
10Before continuing please read our [code of conduct][code-of-conduct] which all
11contributors are expected to adhere to.
12
13[code-of-conduct]: https://github.com/gleam-lang/gleam/blob/main/CODE_OF_CONDUCT.md
14
15
16## Contributing bug reports
17
18If you have found a bug in Gleam please check to see if there is an open
19ticket for this problem on [our GitHub issue tracker][issues]. If you cannot
20find an existing ticket for the bug please open a new one.
21
22[issues]: https://github.com/gleam-lang/gleam/issues
23
24A bug may be a technical problem such as a compiler crash or an incorrect
25return value from a library function, or a user experience issue such as
26unclear or absent documentation. If you are unsure if your problem is a bug
27please open a ticket and we will work it out together.
28
29
30## Contributing code changes
31
32Before working on code it is suggested that you read the
33[docs/compiler/README.md](docs/compiler/README.md) file.
34It outlines fundamental components and design of this project.
35
36Code changes to Gleam are welcomed via the process below.
37
381. Find or open a GitHub issue relevant to the change you wish to make and
39 comment saying that you wish to work on this issue. If the change
40 introduces new functionality or behaviour this would be a good time to
41 discuss the details of the change to ensure we are in agreement as to how
42 the new functionality should work.
432. Update the [CHANGELOG.md](CHANGELOG.md) file with your changes.
443. Open a GitHub pull request with your changes and ensure the tests and build
45 pass on CI.
464. A Gleam team member will review the changes and may provide feedback to
47 work on. Depending on the change there may be multiple rounds of feedback.
485. Once the changes have been approved the code will be rebased into the
49 `main` branch.
50
51We do not accept contributions from AI agents.
52
53
54## Communication with contributions
55
56Open source software development is a social exercise as much as a technical
57one. Bug reports, pull request descriptions, and comments must be written by a
58human, not by AI. We want your knowledge and opinions in your tone of voice; we
59do not want generated text or AI summaries.
60
61You may use software to help you with your English spelling and grammar. If
62your message is translated into English from another language please disclose
63that in your message, so that we understand.
64
65
66## Local development
67
68To run the compiler tests. This will require a recent stable version of Rust,
69Erlang, Elixir, NodeJS, Deno, and Bun to be installed.
70
71If you are using the Nix package manager, there's a [gleam-nix flake](https://github.com/vic/gleam-nix)
72you can use for running any Gleam version or quickly obtaining a development
73environment for Gleam.
74
75```sh
76cargo test
77
78# Or if you have watchexec installed you can run them automatically
79# when files change
80make test-watch
81```
82
83To run the language integration tests. This will require a recent stable
84version of Rust, Erlang, and NodeJS to be installed.
85
86```sh
87make language-test
88```
89
90If you don't have Rust or Cargo installed you can run the above command in a
91docker sandbox. Run the command below from this directory.
92
93```sh
94docker run -v $(pwd):/opt/app -it -w /opt/app rust:latest bash
95```
96
97## Rust development
98
99Here are some tips and guidelines for writing Rust code in the Gleam compiler:
100
101The `GLEAM_LOG` environment variable can be used to cause the compiler to
102print more information for debugging and introspection. i.e.
103`GLEAM_LOG=trace`.
104
105### Clippy linter
106
107Your PR may fail on CI due to clippy errors. Clippy can be run locally like so:
108
109```sh
110cargo clean -p gleam
111cargo clippy
112```
113
114If you have lint errors on CI but not locally upgrade your Rust version to the
115latest stable.
116
117```sh
118rustup upgrade stable
119```
120
121## Operating system specific code
122
123This project is used on FreeBSD, Linux, MacOS, OpenBSD, Windows, and presumably
124other operating systems, so there is some amount of code that needs to be
125different depending on which is it running on. So far this is hidden inside
126dependencies, with the exception of some code for working with file paths in
127tests and for setting file permissions, which is different on Windows. If you
128are working in this area then you may get a CI failure relating to this for
129your first attempt. If you need help resolving any issues do not hesitate to
130ask.