diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..833ab38 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,69 @@ +# Contributing + +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](https://github.com/BlockstreamResearch/SimplicityHL/issues/155) + 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. + +## Small Contributions + +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](https://github.com/BlockstreamResearch/simplicity-lang-org/) +which includes our online documentation. + +## PR Structure + +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 + +## "Local CI" + +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. + +## Review and Merging + +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](https://github.com/bitcoin-core/bitcoin-maintainer-tools/blob/main/github-merge.py) +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). + +# LLMs + +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."