Contribution Guide

Learn how to contribute to Firefly! We encourage everyone with knowledge and passion in IOTA to collaborate with us ❤️

If you have a general or technical question, please see the following resources to find out what you need:

• Official docs: for official information about developing with IOTA technology
• Discord: for real-time chats with the developers and community members
• IOTA Cafe: for technical discussions with the Research and Development Department at the IOTA Foundation
• IOTA StackExchange: for technical and troubleshooting questions

Report a bug 🐞

This section guides you through reporting a bug. Following these guidelines helps maintainers and the community understand the bug, reproduce the behavior, and find related bugs.

What to check

Please check the following list before filing a report:

• Do NOT open a GitHub issue for security vulnerabilities - please contact us at [email protected] instead
• Ensure the bug was NOT already reported by searching among the "Open" issues in the repository
  • If the bug has already been reported and the issue is still open, add a comment to the existing issue instead of opening a new one
  • If the bug has already been reported and an issue has been closed that seems similar to what you're experiencing, open a new issue and include a link to the original issue in the body of your new one

Opening an issue

After checking the above list, open a new issue, and be sure to follow the form, including as many details as possible.

NOTE: Minor changes such as a typo fix can be in their own dedicated PR, however this is NOT required. Submitting the fix(es) requires opening a pull request and referencing the existing issue.

Suggest a feature or enhancement 🗣️

This section guides you through suggesting a new feature. Following these guidelines helps maintainers and the community collaborate to find the best possible way forward with your suggestion.

What to check

Please check the following list before suggesting a new feature or enhancement:

• Ensure that an open discussion about a similar idea does not exists by searching among them here. If one does exist then please write a comment on that discussion presenting your thoughts.

Proposing your changes

After checking the above list, create a new discussion with the appropriate labels (most likely will be some combination of enhancement, feature, and request).

Build a feature or enhancement 🛠️

This section guides you through building a new feature. Following these guidelines helps give your feature the best chance of being approved and merged.

What to check

Please check the following list before building a new feature or enhancement:

• Ensure that an open discussion about a similar idea does not exists by searching among them here. If one does exist then please write a comment on that discussion presenting your thoughts.
• Create a discussion around the idea on GitHub first, which one can do here. This is important as it will help create the best feature for everyone and reduce any wasted time and efforts 👍

CAUTION: Without completing these steps, your changes will be less likely to be approved.

Implementing the new changes

To build a new feature, check out a new branch based on the develop branch, and be sure to document any public-facing APIs. Please follow the coding conventions for the Firefly repository as these will create a smoother process of getting your changes approved and merged 😃

When you feel that your changes are ready, please follow the steps for making a pull request down below.

Make a pull request 📄

This section guides you through submitting a pull request (PR). Following these guidelines helps give your PR the best chance of being approved and merged.

PR style

A PR should have exactly one concern (i.e. a feature or a bug). A PR that addresses more than one concern should ideally be split into multiple PRs.

NOTE: Should you feel the need, please don't hesitate to suggest or make improvements to existing code. There may be cases when larger refactors are best in a dedicated PR, but there are certainly times when more localized code can be improved.

Commits

We use Conventional Commits, so that commit messages are clean and concise. They should follow a consistent structure, being written in present-tense and using the prefixes below:

• chore: modifies documentation, cleaning dependencies, other housekeeping-like tasks
• ci: creates or changes an existing continuous integration workflow (checkout ci.*.yml files in firefly/.github/workflows/)
• feat: introduces a new feature or enhancement of an existing feature
• fix: fixes or patches a bug in app functionality
• refactor: improvements made to existing code
• style: adjusts component styling or UI-only changes
• test: changes made only to unit or integration tests

An example might be:

feat: Add conversion function for IOTA to fiat currency

The granularity of the commits are ultimately up to you, however we prefer keeping the number of commits lower if possible. The commits are squashed in the end as a change-log / summary of the PR, so do not worry too much.

Branches

Branch names must follow a certain structure, which is branch-prefix/branch-name. The branch-prefix corresponds to one of the conventional commit types defined above and the branch name is a concise but informative name representing your changes, e.g. feat/your-cool-feature and chore/new-doc. PR titles are based off of the branch name, so for the examples just used they should be "feat: Your cool feature" and "chore: New doc".

What to check

Please follow these steps when before a pull request:

• Fork the repo and base your new branch from develop
• Add unit tests as needed (refer to the Testing section of the Coding Conventions in the wiki
• Ensure that the code is formatted and linted
• Ensure that the code is tested and passing
• Ensure that the code passes the continuous integration (CI) workflows:
  • Linting CI
  • Testing CI
• If your changes include modification or adding of dependencies, once your PR is approved it must then be merged into a snyk/branch-prefix/branch-name on the main Firefly repository to test said changes with the Snyk continuous integration workflow

Creating the PR

After checking the above list, please issue your pull request. If all status checks pass, and the maintainer approves the PR, it will be merged.

Please be sure to tag any relevant issues or discussions in the PR description as this will help keep the repository clean 🧹

NOTE: Reviewers may ask you to complete additional work, tests, or other changes before your pull request can be approved and merged.

Code of Conduct 📝

This project and everyone participating in it is governed by the IOTA Code of Conduct.