digital-asset/daml
1
1
Fork 0
mirror of https://github.com/digital-asset/daml.git synced 2024-09-20 01:07:18 +03:00
Code Issues Projects Releases Wiki Activity
b30228ab95
daml/CONTRIBUTING.md
Stefano Baghino b2d9095a3c
Move unreleased user-facing features to its own file (#1762) 
* Move unreleased user-facing features to its own file

docs/source/support/release-notes.rst unfortunately represents a "global
lock" when it comes to submitting contributions: if another contribution
changed it while another was going through the CI/review process, the
latter would have to go again through the CI build after resolving the
conflict and merging the resulting commit.

The contributors originally tried to address this problem by letting the
system automatically performing this operation, but this failed because
release notes were moved to the wrong section by mistake.

This simple change would allow the contributors to let the system take
care of merging on its own, because existing release notes will no
longer be corrupted by the process.

There is a caveat: the automatic merging could result in invalid RST
(mostly because of missing newlines). This would push the task of
ensuring the release notes are valid RST to the release. I would argue
this can be done quite easily and that this is checked automatically
when rendering RST to HTML, so it could be a nuisance during release but
it would make the day-to-day contributions easier.

* Address https://github.com/digital-asset/daml/pull/1762#issuecomment-503540993

* Address https://github.com/digital-asset/daml/pull/1762#pullrequestreview-251676158

* Address https://github.com/digital-asset/daml/pull/1762#discussion_r295279530

* Remove HEAD section from release-notes.rst

* Address https://github.com/digital-asset/daml/pull/1762#pullrequestreview-251678791

* Address https://github.com/digital-asset/daml/pull/1762#issuecomment-503549896
2019-06-19 16:32:03 +02:00

5.2 KiB
Raw Blame History

Contributing to DAML

Welcome! This page gives a high-level overview of how to contribute to the development of DAML.

There are many ways you can contribute beyond coding. For example, you can report problems, clarify issues, and write documentation. If you're completely new to open source development, the Open Source Guides is a great place to start.

Working on the codebase

For information on how to build, test, and work on the codebase, see "To start contributing to DAML" in the README.

Code of conduct

This project and everyone participating in it is governed by the DAML Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to community@digitalasset.com.

Git conventions

For Git commit messages, our principle is that git log --pretty=oneline should give readers a clear idea of what has changed and the detailed descriptions should help them understand the rationale. To achieve this:

  • Commits must have a concise, imperative title, e.g.:
    • Fix performance regression in …
    • Improve explanation of …
    • Remove module X because it is not used.
  • Commits should have a description that concisely explains the rationale and context for the change if that is not obvious.
  • Commit descriptions should include a Fixes #XX line indicating what GitHub issue number the commit fixes.
  • The git logs are not intended for user-facing change logs, but should be a useful reference when writing them.

Pull request checklist

  • Read this document (contribution guidelines).

  • Does your PR include appropriate tests?

  • Make sure your PR title and description makes it easy for other developers to understand what the contained commits do. The title should say what the changes do. The description should expand on what it does (if not obvious from the title alone), and say why it is being done.

  • If your PR corresponds to an issue, add “Fixes #XX” to your pull request description. This will auto-close the corresponding issue when the commit is merged into master and tie the PR to the issue.

  • If your PR includes user-facing changes, you must add a line describing the change to unreleased.rst as part of your PR. Each entry in this document must start with the component to which is belongs, as in the following example:

    - [Sandbox] Introduced a new API for package management.
  See `#1311 <https://github.com/digital-asset/daml/issues/1311>`__.

Working with issues

We use issues and pull requests to collaborate and track our work. Anyone is welcome to open an issue. If you just want to ask a question, please ask away on Stack Overflow using the tag daml.

We encourage everyone to vote on issues that they support or not:

  • 👍 - upvote
  • 👎 - downvote

When you start working on an issue, we encourage you to tell others about it in an issue comment. If other contributors know that this issue is already being worked on, they might decide to tackle another issue instead.

When you add TODO (nice to have) and FIXME (should fix) comments in the code, we encourage you to create a corresponding issue and reference it as follows:

  • TODO(#XX): <description> where #XX corresponds to the GitHub issue.
  • FIXME(#XX): <description> where #XX corresponds to the GitHub issue.

Labels

We use labels to indicate what component the issue relates to (component/...). We use some special labels:

  • broken to indicate that something in the repo is seriously broken and needs to be fixed.
  • discussion to indicate the issue is to discuss and decide on something.
  • good-first-issue to indicate that the issue is suitable for those who want to contribute but don't know where to start.

By default, issues represent "work to be done" -- that might be features, improvements, non-critical bug fixes, and so on.

The DAML Language team uses labels to indicate priority (the DAML Runtime team does not):

  • language/now
  • language/soon
  • language/later

You can see all labels here.

Milestones

In addition to labels, we group issues into milestones. The DAML Language team has all issues in a single Language milestone; the DAML Runtime team uses them to group work efforts (Add PostgreSQL backend to the Ledger for example). Maintenance and Backlog are special milestones.

Issues without a milestone are treated as in need of triaging.

You can see all the active milestones here.

Discussions

Please hold discussions that are relevant to DAML development and not confidential in GitHub issues. That way, anyone who wants to contribute or follow along can do so. If you have private discussions, please summarise them in an issue or comment to an issue.

You can also join a #daml-contributors channel on our Slack: damldriven.slack.com.

Thank you!

Thank you for taking the time to contribute!