mirror of
https://github.com/tweag/nickel.git
synced 2024-10-06 08:07:37 +03:00
127 lines
5.7 KiB
Markdown
127 lines
5.7 KiB
Markdown
# Contributing to Nickel
|
|
|
|
Welcome, and thanks for considering contributing to the Nickel project!
|
|
|
|
## Contributing
|
|
|
|
There are many useful ways to help which don't involve modifying the source of
|
|
Nickel:
|
|
|
|
- Improving the documentation, user-facing or internal, technical or high-level
|
|
- Growing the Nickel ecosystem, by providing the community with libraries
|
|
(e.g. a collection of contracts for new use cases), augmenting the
|
|
standard library, or improving the tooling (such as code editor integration).
|
|
- Reviewing changes from other contributors.
|
|
|
|
The rest of this document is concerned with any changes impacting the `nickel`
|
|
repository, which may or may not involve changing the source of Nickel.
|
|
|
|
## Table of content
|
|
|
|
1. [Preamble](#preamble)
|
|
1. [Resources](#resources)
|
|
1. [Set up a development environment](#set-up-a-development-environment)
|
|
1. [How to submit changes](#how-to-submit-changes)
|
|
|
|
## Preamble
|
|
|
|
Before contributing any non-trivial change to this repository, please first
|
|
check for the existence of related work such as issues or open pull requests. If
|
|
there are none, it's better to discuss the change you wish to make via an issue,
|
|
by email, or using any other method with the maintainers of this repository
|
|
(listed below) before actually submitting something.
|
|
|
|
## Resources
|
|
|
|
### Documentation
|
|
|
|
The following resources are oriented toward Nickel users:
|
|
|
|
- The [README](./README.md) and the [design rationale](./RATIONALE.md)
|
|
- The [blog post series][blog-series] and the [release blog post][blog-release].
|
|
- The [user manual][user-manual].
|
|
|
|
For Nickel contributors (or aspiring contributors), the following technical
|
|
documentation is relevant as well:
|
|
|
|
- The [crate documentation][doc-crate].
|
|
- The [RFCs][rfcs]. There is currently no well established process for RFCs, but
|
|
as a rule of thumb, impactful changes to the design or the implementation of
|
|
the language are technically discussed and documented in a dedicated RFC
|
|
document.
|
|
- The [technical notes][doc-notes]. Various notes gathering thoughts, proposals,
|
|
or issues about an aspect of the language at one point in time that the author
|
|
thought important to keep for posterity. They are usually more informal than
|
|
RFCs, of smaller scope, and their content may become obsolete more easily.
|
|
|
|
### People
|
|
|
|
Nickel is maintained by [Tweag][tweag]. The current lead maintainer is Yann
|
|
Hamdaoui (@yannham).
|
|
|
|
You can find some of us on our [matrix channel][matrix-nickel] (and in
|
|
particular the Devs room), or fire an email at `nickel-lang@tweag.io`.
|
|
|
|
## Set up a development environment
|
|
|
|
Please refer to [`HACKING.md`](./HACKING.md) to set up a development environment
|
|
for Nickel, as well as adding or running tests and benchmarks.
|
|
|
|
## How to submit changes
|
|
|
|
**Try to keep pull requests small and focused**. Avoid packing refactoring,
|
|
cosmetic changes or anything not directly related to your original goal in the
|
|
same pull request. If preliminary steps make sense as standalone changes, don't
|
|
hesitate to split your pull request into several ones. There are a couple
|
|
aspects to consider when working on Nickel:
|
|
|
|
1. **Documentation**: If you added new items (functions, modules) to the public API
|
|
of a crate, please document those items in-code. If you made a user-facing
|
|
change (syntax, stdlib, language features, etc.), please update the existing
|
|
documentation (in particular the user-manual) in consequence.
|
|
2. **Tests**: be it for bug fixing or adding new features, please try to write
|
|
extensive tests as much as possible, to ensure the correctness of your
|
|
changes as well as avoiding regressions.
|
|
3. **Benchmarks**: if your change is likely to impact the performance in a
|
|
non-trivial way, it might be useful to run the benchmark suite on both master
|
|
and on your branch and to report those results in the description of the PR.
|
|
|
|
## The review process, or how to get your PR merged
|
|
|
|
The conditions to merge a PR are whatever GitHub branch protection rules are
|
|
currently set by the Nickel repository. If a PR has the green button available
|
|
on GitHub, then this PR meets the conditions to be merged. Conditions usually
|
|
include at least one review from a maintainer and a green CI.
|
|
|
|
### As an external contributor
|
|
|
|
As an external contributor, the Nickel team is responsible for giving your code
|
|
a first review. Once done, they might require changes or ask questions. From
|
|
there, please try to address every review comment (and resolve the corresponding
|
|
conversation on GitHub), and request a new review once done.
|
|
|
|
### As a maintainer
|
|
|
|
If you are reviewing an external contributor's PR, _you are responsible for
|
|
merging or rejecting the PR_. In general, you should only give an "Accept" if
|
|
everything has been sorted out, and you're ready to click the green button
|
|
without needing another back-and-forth with the author.
|
|
|
|
If the author of a PR has commit rights (such as a Tweager or a Nickel
|
|
maintainer), _they are responsible for merging their change_. This includes
|
|
requiring review from the right people. When reviewing such PRs, you can leave
|
|
an "Accept" although you made review comments: this indicates that you are fine
|
|
with the work being merged as it is, but you have minor suggestions and
|
|
questions that the author might want to consider. You trust the author to do
|
|
whatever they think is best and proceed with merging the PR from there. This
|
|
minimizes back-and-forths with trusted authors.
|
|
|
|
[blog-series]: https://www.tweag.io/blog/2020-10-22-nickel-open-sourcing/
|
|
[blog-release]: https://www.tweag.io/blog/2022-03-11-nickel-first-release/
|
|
[user-manual]: https://nickel-lang.org/user-manual/introduction/
|
|
[doc-crate]: https://docs.rs/nickel-lang/0.1.0/nickel_lang/
|
|
[doc-notes]: notes/
|
|
[tweag]: https://www.tweag.io
|
|
[rfcs]: ./rfcs/
|
|
[matrix-nickel]: https://matrix.to/#/#nickel-lang:matrix.org
|