Skip to content

Latest commit

 

History

History
119 lines (90 loc) · 5.27 KB

CONTRIBUTING.md

File metadata and controls

119 lines (90 loc) · 5.27 KB
Raw

Contribution Guidelines

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119.

These keywords SHALL be in monospace for ease of identification.

Continuous integration and development

pre-commit

This repository uses pre-commit. If you add a new filetype, you SHOULD add a new hook. See adding new hooks for additional info.

In the cfg/ directory are all of the pre-commit configuration files for various hooks.

To set up your local workspace to use pre-commit or change any of the hook configurations, please see the pre-commit configuration README.

If you'd like to run our Python formatter locally to pass pre-commit checks, you can run our Python format script.

GitHub actions

This repository uses GitHub actions to perform assorted status checks. If you submit a pull request but do not run pre-commit then your pull request might get blocked.

Pull requests

This repository handles pull requests (PRs) using the squash and merge method.

The Econia Labs team uses Linear for project management, such that PRs titles start with tags of the form [ECO-WXYZ]. All PRs MUST include a tag, so if you are submitting a PR as a community contributor, an Econia Labs member SHALL change your PR title to include an auto-generated tag for internal tracking purposes.

Pull requests MUST include a description written using imperative form that "tells the repository what to do".

Pull request titles MUST also use imperative form, with the first letter after the tag capitalized. For example [ECO-WXYZ] Update something in the repo.

Commit titles SHOULD use a similar format, but without a leading tag.

Resolution of a review comment SHALL be reserved for the reviewer who made the comment, except for the case of suggestion acceptance, which automatically results in the comment being marked as resolved.

Move design phases

Preliminary

  1. During preliminary design phases, design SHALL emphasize abstraction and ease of testing, with optimizations in mind, for example, to reduce borrows.
  2. Asserts SHALL be wrapped in helper functions to reduce failure tests.
  3. Inlining SHALL only be used for functions that pass up a reference to a borrow out of global storage.

Style

General

  1. Incorrect comments are worse than no comments.
  2. Minimize maintainability dependencies.
  3. Prefer compact code blocks, delimited by section comments rather than whitespace.
  4. Titles SHALL use Title Case while headers SHALL use Sentence case.
  5. Comments SHALL start with a capital letter and end with a period ., even if they are a single line.

Markdown

  1. Reference links are REQUIRED where possible, for readability and for ease of linting.
  2. LaTeX display equations SHALL be delimited via a math fenced code block (note that you can render these locally using the gitlab delimiter for the VS Code Markdown+Math extension).

Move

  1. Reference variable names MUST end in either _ref or _ref_mut, depending on mutability, unless they refer to signers.
  2. Doc comments MUST use Markdown syntax.
  3. Variable names SHOULD be descriptive, with minor exceptions for scenarios like math utility functions.
  4. Error code names MUST start with E_, for example E_NOT_ENOUGH_BASE.
  5. Where possible, functions of the form ensure_property_x(), which ensure that some property holds, SHALL be favored over functions of the form assert_property_x(), which abort if a property does not hold.
  6. Until a formatter or linter is available, lines SHALL break at 100 characters per the Move formatting guidelines.
  7. Events SHALL be titled in the form Something, as opposed to SomethingEvent, and SHALL be emitted v2-style, consistent with the Aptos Framework v2 event refactors.