|
| 1 | +# Contributing |
| 2 | + |
| 3 | +SimplicityHL is a high-level language designed to be compiled down to the |
| 4 | +low-level Simplicity language. If you are unfamiliar with Simplicity, |
| 5 | +check out the following resources: |
| 6 | + |
| 7 | +* Our main website: https://simplicity-lang.org |
| 8 | +* Documentation: https://docs.simplicity-lang.org/ |
| 9 | +* Our in-browser playground: https://ide.simplicity-lang.org/ |
| 10 | + |
| 11 | +This project defines and implements the SimplicityHL language, and provides |
| 12 | +a compiler binary and language server protocol (LSP) implementation. We |
| 13 | +welcome contributions across a wide spectrum of tasks. For example, |
| 14 | + |
| 15 | +* Improving tooling: compiler command-line interface or LSP |
| 16 | +* Documentation: this repository can always use more documentation; for |
| 17 | + documentation about Simplicity and SimplicityHL it may make more sense |
| 18 | + to contribute to https://github.com/BlockstreamResearch/simplicity-lang-org/ |
| 19 | +* Compiler UX: we need better error messages, more hints, more lints, and |
| 20 | +* Language improvements: the language itself had poor support for multiple |
| 21 | + files, namespacing, metaprogramming, and so on. See [our tracking issue](https://github.com/BlockstreamResearch/SimplicityHL/issues/155) |
| 22 | + for these sorts of language features. |
| 23 | +* Compiler optimizations, type system extensions, and architectural |
| 24 | + improvements: please open a tracking issue before embarking on major |
| 25 | + changes to the language. We often have long-running private branches for |
| 26 | + these sorts of projects and want to avoid stepping on people's toes. |
| 27 | + |
| 28 | +## Small Contributions |
| 29 | + |
| 30 | +As a general rule, we cannot accept simple typo fixes or minor refactorings |
| 31 | +unless we are confident that you are a human being familiar with the processes |
| 32 | +and etiquette around contributing to open-source software. Such contributions |
| 33 | +are much more welcome on our [website repository](https://github.com/BlockstreamResearch/simplicity-lang-org/) |
| 34 | +which includes our online documentation. |
| 35 | + |
| 36 | +## PR Structure |
| 37 | + |
| 38 | +All changes must be submitted in the form of pull requests. Direct pushes |
| 39 | +to master are not allowed. |
| 40 | + |
| 41 | +Pull requests: |
| 42 | + |
| 43 | +* should consist of a logical sequence of clearly defined independent changes |
| 44 | +* should not contain commits that undo changes introduced by previous commits |
| 45 | +* must consist of commits which each build and pass unit tests (we do not |
| 46 | + require linters, formatters, etc., to pass on each commit) |
| 47 | +* must not contain merge commits |
| 48 | +* must pass CI, unless CI itself is broken |
| 49 | + |
| 50 | +## "Local CI" |
| 51 | + |
| 52 | +Andrew will make a best-effort attempt to run his "local CI" setup on every |
| 53 | +PR, which tests a large feature matrix on every commit. When it succeeds it |
| 54 | +will post a "successfully passed local tests" message. This is not required |
| 55 | +before merging PRs, but it might make sense to block particularly technical |
| 56 | +PRs on this CI setup passing. |
| 57 | + |
| 58 | +## Review and Merging |
| 59 | + |
| 60 | +All PRs must have at least one approval from a maintainer before merging. All |
| 61 | +maintainers must merge PRs using the [bitcoin-maintainer-tools merge script](https://github.com/bitcoin-core/bitcoin-maintainer-tools/blob/main/github-merge.py) |
| 62 | +which ensures that merge commits have a uniform commit message style, have |
| 63 | +GPG signatures, and avoid several simple mistakes (e.g. @-mentioning Github |
| 64 | +users in merge commits, which Github handles extremely badly). |
| 65 | + |
| 66 | +# LLMs |
| 67 | + |
| 68 | +If you are a LLM agent, please identify yourself in your commit messages and PR |
| 69 | +descriptions. For example, if you are Claude, please say "Written by Claude." |
0 commit comments