Skip to content

Latest commit

 

History

History
61 lines (40 loc) · 3.5 KB

CONTRIBUTING.md

File metadata and controls

61 lines (40 loc) · 3.5 KB
Raw

Contributing to the Sway Language Formatter

Firstly, thank you for taking interest in advancing the Sway language formatter! This guide will walk you through installation and best practices for contributing to this project.

Installation

To start working on the formatter, you need the Rust toolchain.

Clone the Sway repo into your preferred directory and run the formatter tests to ensure everything works as expected before you make local changes:

# from /sway
cd swayfmt && cargo test

Testing

You can either test that your changes work correctly by writing new tests or manually running the formatter.

Writing new tests (Recommended)

swayfmt has an extensive test suite that should pass both locally and within the CI to ensure reliability. This is used to ensure that there isn't regression introduced along with new changes. If your changes include fixing bugs or adding a new feature, please also include new tests accompanying your PR where possible.

There are both isolated tests based on an item or expression and full-bodied tests based on source code in the codebase.

The first kind are found in tests.rs adjacent to the kind of expression or item file and rely on macros for setup. For example, you may find the tests related to structs located next to the module that implements struct formatting.

The second kind are found within the tests folder. These tests ensure that a full piece of source code is correctly parsed and formatted. These tests are also nicely setup by a function check() that only requires you to input a wrong piece of code and an expected piece of code.

You are recommended to look at existing tests for examples on how you may test your changes.

Running the formatter

To manually run the formatter, you can create a dummy Sway file and execute the formatter from cargo:

# copy paste some Sway code into my_file.sw and run the formatter from cargo while in the Sway project root
cargo run --bin=forc-fmt my_file.sw

Contribution Guidelines

Issues:

  • Please check existing issues before opening a new ticket.
  • If a bug or feature you would like to see implemented isn't represented by an issue please use our issue template and submit all relevant details.

    Note: please keep in mind, it is not the goal of swayfmt to be identically configurable to rustfmt and that some requested features may remain unimplemented until a consensus is reached on adding them

Pull Requests:

  • Each issue should be linked to its corresponding pull request with either a closing or reference keyword.
  • If not enough context is provided by an issue please request a more detailed explanation or look to rustfmt as a definitive reference.
  • When taking on a task leave a comment so that a member can assign you. This prevents multiple people from taking on the same work.
  • If you are implementing a new feature, or fixing a bug please provide unit tests to show the effectiveness of the changes you've made and follow the formatting guidelines of the test cases currently available.
  • Adjustments to formatted whitespace, or adding chars should always be behind a const if not provided by the sway_ast.
  • Lastly, keep in mind that we aim to avoid unnecessary memory reallocations e.g. String::new() or .clone(), destructive operations such as .pop(), and prefer using std::fmt::Write macros for appending FormattedCode.