# How to report an issue

For us to ensure proper planning for any bugfix or feature development workflow, we appreciate if our beloved reporters follow the below guidelines 😃

# Use issue tracker for the right purpose

As part of maintaining our OSS workflow, StorefrontUI uses Github issue tracker ONLY for bugs and feature requests (RFC).

WARNING

  • It is NOT for requesting personal support or asking a question. Use our Discord Server or Stack Overflow or even Twitter.
  • It is NOT for social media, respect others' opinions, and proper languages are required.

# Issue types

For organizing and tracking purpose, we divide issues on StorefrontUI into the following main types:

  • Bug report
  • Feature request (RFC)

# Before reporting

Please do the following checks:

  • Double-check the current issues with the help of Github issue search, to avoid report duplication.
  • If it is an issue about component behavior, check our Components Playground or Components Documentaton to make sure it is indeed a bug 🐛 and not an intended feature.
  • If it's about technical questions or just to verify it is technical related, refer to our Discord Server first. Our contributors and core team will be more than happy to help.
  • Besides, if it is about feature request, refer to our current Roadmap to see if your request exists.

Once you verify your issue from the above checks, it's time to create a new report using Github issue tracker with the right template recommendations below.

# Issue template

Issue title is the first impression of the developer to identify the issue quickly. A good title should contain a brief, clear, and concise explanation with the essential key points.

GOOD TITLE

[BUG]Precommit checks for shared package fail

BAD TITLE

Can't commit.

# Feature requests (RFC)

OSS projects can't live without improvements 😉. So feature requests are always welcome.

WARNING

Please take a moment to validate if your request is within the scope of StorefrontUI by contacting us on Discord Server, or DM to @StorefronUI

Our feature request, unlike the bug report, is straightforward. There are two main fields needed for developers' understanding:

# User story

A user story is the use case of the requested feature. To convince developers of the need for this feature, try to clarify as many aspects and context related to the feature as possible, such as:

  • What is the user flow of the feature?
  • What is expected?
  • What generic problem does this feature solve?
  • Any other benefit this feature provides users?

The more details you provide, the stronger and clearer your request will appear to developers.

# Description / Proposed idea

Sometimes developers get developer-block also. It's similar to writer-block. And not all developers are good at proposing feature API. In such circumstances, it's constructive to give them a hint or your suggestion on how you think we should develop the feature. Sharing is caring.

# Bug report

Bug report template is the standard placeholder for every new bug found.

TITLE WITH PREFIX

Bug report will be populated with a title prefix [BUG] upon creation:

[BUG]<bug issue title>

As always, some crucial pre-guidelines:

  1. If the issue has been fixed before, try to reproduce it with the latest master branch.
  2. To help us understand the exact problem, make an effort to isolate the problem by a reduced test case, steps to reproduce and a live example if possible.

A GOOD BUG REPORT

A good bug report should be clear, as detailed as possible without the need of chasing for more information.

# General description

What is the bug you are reporting? Summary the bug in a bit of more details (but still concise) than the bug title.

# Steps to reproduce

It is the most significant part, allowing the developer to reproduce the issue and backtrack why it happens. If a bug can be reproduced, it's 90% fixable.

Hence developers need you to describe each step precisely, even the most and seem-less-important detail.

Example:
1. Navigate to Contributing.md
2. Click on Become A Contributor link.

If possible, include a live record of the reproducing process, so that we can avoid any misunderstanding and unnecessary ping pong conversations between reporter and developer.

# Expected & actual behavior

It's a must to state the result you expect and the observed one so everyone is in sync on the bug and clarify in case there is any mismatch.

Examples:
Expected behavior: Open link to become a contributor documentation page.

Actual behavior: Received 404 page.

# Code examples

If there is any code or extra configuration involved (like how you use the component in practice), don't forget to include them. Either CodeSandbox or simply Markdown code is acceptable.

# Additional information

In addition to the above fields, more information may be required to speed up bug fix, including:

  • Screenshots - It can be console logs, terminal logs, actual problematic behavior, etc.
  • Environment - It can be which browser, OS, and devices that relate to the issue.
  • Repository branch, the version used, tech stacks used, etc.

Interested in becoming contributors? Reach out to us @StorefrontUI or in our Discord Server 🔥