Skip to content

Latest commit

 

History

History
173 lines (130 loc) · 6.88 KB

CONTRIBUTING.md

File metadata and controls

173 lines (130 loc) · 6.88 KB

Dune is an community orientated open source project. It was originally developed at Jane Street and is now maintained by Jane Street and Tarides together with several developers from the OCaml community.

Sharing feedback

The easiest way to contribute is to share feedback.

We discuss bugs reports and feature requests via our issues. If you don't find a preexisting issue discussing your topic, then please file a new issue.

For other kinds of support, feedback, or questions, please contribute to our discussions.

Developing Dune

Contributions to the Dune code base are welcome!

Our development process is as follows:

  • Non-trivial submissions should be preceded by an issue communicating the rationale for the intended change.
  • Substantial changes should be preceded by upfront design and planning, proportional to the scope and impact of the intended change.
    • This design should be reviewed by at least one other party.
    • GitHub issues are an appropriate venue for most design discussions, but more involved design work may warrant an RFC or ADR.
  • GitHub is the preferred venue for discussing architectural and design decisions. Exchanges in meetings and chat are valuable, but we insist on deliberating and recording the what and why of our work in the persistent record of GitHub.
  • Changes are submitted via GitHub pull requests against the main branch.
  • Technical changes must appear in the project Changelog. Learn more on how to update the changelog.

If you are looking to get started, check our issues tagged with good first issue or help wanted.

Developer documentation

See our developer documentation at ./doc/hacking.rst or online for technical guidance about contributing to the code base.

Developer meetings

See our developer wiki for the latest information about our recurring developer meetings. All interested attendees are welcome.

Signing contributions

Dune is distributed under the MIT license and contributors are required to sign their work in order to certify that they have the right to submit it under this license.

Your signature certifies that you wrote the patch or otherwise have the right to pass it on as an open-source patch. The rules are pretty simple: if you can certify the below (from developercertificate.org):

Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
1 Letterman Drive
Suite D4700
San Francisco, CA, 94129

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.


Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.

Then you just add a line to every git commit message:

Signed-off-by: Joe Smith <joe.smith@email.com>

Use your real name (sorry, no pseudonyms or anonymous contributions.)

If you set your user.name and user.email git configs, you can sign your commit automatically with git commit -s.

It is possible to set up git so that it signs off automatically by using a prepare-commit-msg hook in git. See https://stackoverflow.com/a/46536244 for details. As noted in the manual for format.signOff, note that adding the Signed-off-by trailer should be a conscious act and means that you certify you have the rights to submit this work under the same open source license.

Updating the Changelog

In Dune, the Changelog is in CHANGES.md. As there are many contributions at the same time and to prevent an infinite cycle of rebases, the CHANGES.md file is only updated when releasing Dune. Unreleased changes are recorded inside doc/changes/. The name of the file is <PR number>.md. Depending on the nature of the change, it can live inside three categories: added, changed, fixed, where:

  • added records every new feature or behaviour visible to users
  • changed records a difference of behaviour with the previous version
  • fixed records any change that restores the behaviour as expected

An entry follows this format where fixes is optional if it is not linked to any issue:

- A small description about what this entry is doing and what this changes
  brings to the users. Try to imagine what people will understand when reading
  the changelog. (#<PR number>, fixes #<issue number>, @author1, @author2)

The entry must fit in 80 columns of text. Most of the editors allows formatting the size of the text using a column size.

In Dune, we try to avoid breaking changes by versioning our features with a (lang dune <version>) system. However, if the change you introduce is a breaking change, the entry must start with BREAKING CHANGE:. The entry would be:

- BREAKING CHANGE: A small description about what this entry is doing and what
  this changes brings to the users. Try to imagine what people will understand
  when reading the changelog. (#<PR number>, fixes #<issue number>, @author1,
  @author2)