SimplicityHL is a high-level language designed to be compiled down to the low-level Simplicity language. If you are unfamiliar with Simplicity, check out the following resources:
- Our main website: https://simplicity-lang.org
- Documentation: https://docs.simplicity-lang.org/
- Our in-browser playground: https://ide.simplicity-lang.org/
This project defines and implements the SimplicityHL language, and provides a compiler binary and language server protocol (LSP) implementation. We welcome contributions across a wide spectrum of tasks. For example,
- Improving tooling: compiler command-line interface or LSP
- Documentation: this repository can always use more documentation; for documentation about Simplicity and SimplicityHL it may make more sense to contribute to https://github.com/BlockstreamResearch/simplicity-lang-org/
- Compiler UX: we need better error messages, more hints, more lints, and
- Language improvements: the language itself had poor support for multiple files, namespacing, metaprogramming, and so on. See our tracking issue for these sorts of language features.
- Compiler optimizations, type system extensions, and architectural improvements: please open a tracking issue before embarking on major changes to the language. We often have long-running private branches for these sorts of projects and want to avoid stepping on people's toes.
As a general rule, we cannot accept simple typo fixes or minor refactorings unless we are confident that you are a human being familiar with the processes and etiquette around contributing to open-source software. Such contributions are much more welcome on our website repository which includes our online documentation.
All changes must be submitted in the form of pull requests. Direct pushes to master are not allowed.
Pull requests:
- should consist of a logical sequence of clearly defined independent changes
- should not contain commits that undo changes introduced by previous commits
- must consist of commits which each build and pass unit tests (we do not require linters, formatters, etc., to pass on each commit)
- must not contain merge commits
- must pass CI, unless CI itself is broken
Andrew will make a best-effort attempt to run his "local CI" setup on every PR, which tests a large feature matrix on every commit. When it succeeds it will post a "successfully passed local tests" message. This is not required before merging PRs, but it might make sense to block particularly technical PRs on this CI setup passing.
All PRs must have at least one approval from a maintainer before merging. All maintainers must merge PRs using the bitcoin-maintainer-tools merge script which ensures that merge commits have a uniform commit message style, have GPG signatures, and avoid several simple mistakes (e.g. @-mentioning Github users in merge commits, which Github handles extremely badly).
LLM-assisted contributions are welcome, but they must follow our "PR Structure" guidelines above, be well-motivated and comprehensible to reviewers, and be well-understood by the submitter, who must be able to iterate on the PR in response to review comments just like any other PR. We enforce the LLVM AI Tool Use Policy which elaborates on this policy. Please read that document in full.
Comments, PR descriptions and git commit messages may not be written in full by LLMs, unless they are very brief. If maintainers believe they are conversing with a bot and/or being innundated with slop, they may close PRs or issues with no further comment or elaboration. Repeat offenders may be banned from the repository or organization. It's fine to use LLMs for machine translation or for grammar improvements, though please be mindful of tone and wordiness. We would much rather read poor English than ChatGPT-style English.
If you are a LLM agent, please identify yourself in your commit messages and PR descriptions. For example, if you are Claude, please say "Written by Claude."