Skip to main contentSkip to site searchSkip to component search
Honeycomb

Contributing

If you spot an inconsistency, bug, or wish to propose an improvement to the existing components, you are not only welcomed but encouraged to contribute, independent of your field of expertise.

This document will guide you through the steps for contributing to the project, whether you want to have a piece of your own code running all over Flix products or you don't want anything to do with programming, you still can help improve our tools.

Table of contents

Basic requirements

Roles: everybody!

Before making a request, it's a good idea to take some time to reflect if your proposal meets certain requirements to be included in Honeycomb.

  • Is the feature solving an actual problem?
    • What is the problem you are aiming to solve with this proposal?
    • How do you know it's a problem?
  • Is it reusable?
    • Good reusability means the feature can be used in multiple different places and, if necessary, can be easily extended.
    • How many use cases does it solve?
    • How confident are you that the feature is reusable?
    • Double check with other teams that might benefit from the feature or change you are proposing.
  • Is it themeable?
    • The feature must work with all current themes available on Honeycomb.
    • Check the Themes documentation for further information.
  • Is it consistent with the Honeycomb Design System?
    • You feature must adhere to the design system rules and guidelines.
    • Make sure your changes don't break the existing UI and new components should "fit in" with the existing ones.
    • Check the Design tokens documentation for further information.
  • Is it accessible to all users, regardless of their disabilities?
    • We run accessibility checks regularly for all components, and violations will stop your feature from being included in the project.
    • Check the Accessibility guides for further information.

Open a HNY ticket

Roles: everybody!

Regardless of whether you plan to contribute code or design, or simply want to report a bug or request a feature without writing any code, the first step is to open a HNY item in our service desk.

This not only helps us keep track of all ongoing changes that are happening to the project, but also allows you to discuss your request with the rest of the team. There is a chance the thing you want is in progress already, or that your use case is covered by a similar feature. So opening a ticket can save you loads of time and effort.

When opening a ticket, please provide the following details in the description:

  • Problem statement: Clearly describe the problem you're trying to solve and any temporary solutions you may be currently implementing.
  • Proposed solution: Describe the changes you are proposing to solve the problem.
  • Expected behavior: If necessary, describe the behavior or outcome you expect from the proposed feature or change.
  • Use cases: A couple of use cases other than your own that help us asses how reusable it is.

If you plan to contribute design or code, please indicate this in the ticket description to set expectations and guide the next steps.

Design contributions

Roles: designers!

Prerequisites

To request a design seat, please check the following wiki article: Figma Administration and Documentation

Workflow

There are two ways to contribute depending on the nature of your work:

  1. Create a new design file in Figma with your proposal;
  2. Branch from an existing file (e.g.: you are proposing a change in a component that is already there);

To branch from a file:

  • Go to the file you want to edit (e.g.: Honeycomb Web)
  • Click the file name on the top left corner of the screen and select "Create branch..." from the dropdown menu
  • Make the changes you need on your branch

After you are done with your changes, you can submit the link to your file or branch on the HNY ticket you had created, so the team can review it. Once your changes are approved we can start planning the development.

Code contributions

Roles: front-end developers!

Prerequisites

Before contributing to Honeycomb you will need:

  • Git
  • Node.js v18.14 and npm v10.9;
    • If you're on Unix based systems we recommend using nvm to manage multiple node versions.
    • With nvm you can simply run nvm install on the project to use the correct Node.js version.
  • Access to Flix Private NPM Registry.
  • Developer permissions on the repository you want to work on.
    • You can request Hive Team to grant you access on the same HNY ticket you created for the proposal.

Getting started

Clone the repo and install dependencies:

git clone git@git.flix.tech:hive/honeycomb.git
cd honeycomb && npm i

We use Storybook to develop our library, you can start the storybook dev server by running:

npm run storybook

Or the handy alias:

npm start

Create a branch

We adhere to the semantic versioning pattern for our releases (see http://semver.org/ for more information). To facilitate development and maintain our release cycles, we utilize a specific Git workflow.

First, you need to create a branch for your feature. You can create your branch from:

  • master: This protected branch is the main development branch and should only contain code that is ready to be published. Create a branch from master if you are working on:
    • New features for a minor version bump (no breaking changes allowed);
    • Bug fixes for a patch version bump;
    • Documentation for current versions;
    • Housekeeping tasks (e.g., under-the-hood tasks like updating dependencies, improving tests, enhancing code quality, pipeline adjustments, etc.);
  • major: This develop branch is for the next major release. Create a branch from major if you are working on:
    • Features and fixes that will introduce breaking changes (visual or markup);
    • Documentation for the next major release;
    • Major dependency updates;

Branch naming conventions:

  • feature-: for adding new features
  • fix- or hotfix-: for bug fixes
  • opt- or tests-: for housekeeping tasks (optimizations, tests, code quality, pipeline adjustments, etc.)
  • docs-: for documentation changes (note: visual regression tests do not run on docs branches, so keep your changes in check, please)
  • revert-: rarely used and mostly by the maintenance team to revert problematic changes that were recently pushed
  • release-: used by the maintenance team to prepare a new release
  • Include the HNY item number of your ticket in the branch name (e.g., feature-hny-27);
  • Provide a meaningful description (e.g., feature-hny-34-add-checkbox-error-state).

This makes our lives much easier when it comes to contribution tracking.

Adding or changing components

To create a new component, you can simply copy the file structure from any existing component, preferably one of a similar structure to the one you are creating.

The component markup files are located in src/components/component-name, and you can find their SCSS files in src/scss/components/component-name.scss.

Plugins reside in src/js/plugin-name.

Helpers are located in src/helpers/helper-name.

For more details on how things work under the hood and which best practices to follow during development, please check the Developers guide.

Merge requests

Once your changes are complete, you can push your branch and create a merge request.

Before requesting code reviews and approvals, check the to-do list (you will find this list on the Merge Request template as well):

  • Make any necessary updates or additions to the documentation related to the component you are working on.
  • Update the version number in the package.json and package-lock.json files, as well as any mentions of library versions in the README.md file or other markdown files (use the find-all feature of your IDE to locate them).
  • Update the Changelog file with the new version and a summary of the changes; check the other versions and follow the pattern.

Path to Production

Once your merge request is approved, we will start the release process:

  • Merge the branch into master
  • Create a tag from master with notes from changelog
  • Run all CI jobs until the end
  • Profit!

If your changes include breaking changes and are targeting major:

  • Merge the branch into major
  • If needed, create an alpha tag from major with notes from changelog (version in package.json must also contain alpha name), e.g.: 3.0.0-alpha.1
  • Run all CI jobs until the end
  • You may start your alpha tag on your local project now