Skip to main content

Contributing Guide

Thanks for your interest in contributing to this project! This document aims to serve as a friendly guide for making your first contribution.

High-level Etcher overview​

Make sure you checkout our ARCHITECTURE.md guide, which aims to explain how all the pieces fit together.

Developing​

Prerequisites​

Common​

pip install -r requirements.txt

You might need to run this with sudo or administrator permissions.

Windows​

You might need to npm config set msvs_version 2019 for node-gyp to correctly detect the version of Visual Studio you're using (in this example VS2019).

The following MinGW packages are required:

  • msys-make
  • msys-unzip
  • msys-zip
  • msys-bash
  • msys-coreutils

macOS​

It's not enough to have Xcode Command Line Tools installed. Xcode must be installed as well.

Linux​

  • libudev-dev for libusb (for example install with sudo apt install libudev-dev, or on fedora systemd-devel contains the required package)

Cloning the project​

git clone --recursive https://github.com/balena-io/etcher
cd etcher

Running the application​

GUI​

# Build and start application
npm start

Testing​

To run the test suite, run the following command:

npm test

Given the nature of this application, not everything can be unit tested. For example:

  • The writing operating on real raw devices.
  • Platform inconsistencies.
  • Style changes.
  • Artwork.

We encourage our contributors to test the application on as many operating systems as they can before sending a pull request.

The test suite is run automatically by CI servers when you send a pull request.

We make use of EditorConfig to communicate indentation, line endings and other text editing default. We encourage you to install the relevant plugin in your text editor of choice to avoid having to fix any issues during the review process.

Updating a dependency​

  • Install new version of dependency using npm
  • Commit both package.json and npm-shrinkwrap.json.

Diffing Binaries​

Binary files are tagged as "binary" in the .gitattributes file, but also have a diff=hex tag, which allows you to see hexdump-style diffs for binaries, if you add the following to either your global or repository-local git config:

$ git config diff.hex.textconv hexdump
$ git config diff.hex.binary true

And global, respectively:

$ git config --global diff.hex.textconv hexdump
$ git config --global diff.hex.binary true

If you don't have hexdump available on your platform, you can try hxd, which is also a bit faster.

Commit Guidelines​

See COMMIT-GUIDELINES.md for a thorough guide on how to write commit messages.

Sending a pull request​

When sending a pull request, consider the following guidelines:

  • Write a concise commit message explaining your changes.

  • If applies, write more descriptive information in the commit body.

  • Mention the operating systems with the corresponding versions in which you tested your changes.

  • If your change affects the visuals of the application, consider attaching a screenshot.

  • Refer to the issue/s your pull request fixes, so they're closed automatically when your pull request is merged.

  • Write a descriptive pull request title.

  • Squash commits when possible, for example, when committing review changes.

Before your pull request can be merged, the following conditions must hold:

  • The linter doesn't throw any warning.

  • All the tests pass.

  • The coding style aligns with the project's convention.

  • Your changes are confirmed to be working in recent versions of the operating systems we support.

Don't hesitate to get in touch if you have any questions or need any help!