nickel/CONTRIBUTING.md

Contributing to Nickel

Welcome, and thanks for considering contributing to the Nickel project!

A great first step is to join our server.

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
2. Resources
3. Set up a development environment
4. 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 and the design rationale
• The blog post series and the release blog post.
• The user manual.

For Nickel contributors (or aspiring contributors), the following technical documentation is relevant as well:

• The crate documentation.
• The 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. 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. The current lead maintainer is Yann Hamdaoui (@yannham).

You can find some of us on our discord channel (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 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.