Skip to content

Latest commit

 

History

History
190 lines (142 loc) · 9.04 KB

CONTRIBUTING.md

File metadata and controls

190 lines (142 loc) · 9.04 KB
Raw

Contributing Guidelines

We are really excited that you want to contribute to the Interface X open source project! For more information about the Interface X ecosystem and our product roadmap, see the project’s README.

To make it easier for everyone, we’ve put together a set of guidelines for contributing to the Interface X project and its packages, which are hosted in the Empathy Organization on GitHub.

Don’t take these guidelines as hard and fast rules. Use your best judgment, and feel free to propose changes in a pull request.

And above all, a heartfelt thank you for making the time to contribute. We’re delighted to have you alongside!

Table of Contents

Code of Conduct

This project and everyone who participates in it is governed by the Interface X Code of Conduct. By participating, you are expected to adhere to this code. Please report any unacceptable behavior to [email protected].

What you need to know before getting started

Interface X and Packages

Interface X is composed of different packages. New packages will be added here as the project evolves.

  • @empathyco/x-components - This is the core package of the project. These standalone and configurable building blocks allow you to quickly construct the search UI for your shop.
  • @empathyco/x-archetype - This associated project is Empathy’s vision of the ideal mix of X Components. A project showing the power of the X Components, ready to connect to any search API with customizable layout through design tokens. It is the perfect example to learn how to use the X Components. This package is a project outside this monorepo.
  • @empathyco/x-deep-merge - This package clones an array of objects into another object.
  • @empathyco/eslint-plugin-x - Customized version for the Interface X project of the ESLint plugin, an open source JavaScript linting utility. It also includes a style formatter and best practices beyond the ESLint plugin, such as prettier.
  • @empathyco/x-jest-utils - Jest extensions for easier testing.
  • @empathyco/x-logger - A custom implementation of a logger.
  • @empathyco/x-adapter - A set of tools to manage trough schemas API calls and transform the responses to map it to x-types
  • @empathyco/x-adapter-platform - A x-adapter implementation to manage requests and responses to Empathy Platform APIs
  • @empathyco/x-types - TypeScript types & guards for X models.
  • @empathyco/x-storage-service - Storage service with TTL.
  • @empathyco/x-react-wrapper - A proxy that transforms Vue components into React components.
  • @empathyco/x-translations - A project that allows you to import and export the translations.
  • @empathyco/x-utils - provides utilities to ease the development.
  • @empathyco/x-archetype-utils - provides utilities to ease the development. It's used in the Interface X Archetype project.
  • @empathyco/x-bus - provides an event bus to help with event orchestration.
  • @empathyco/x-tailwind - Empathy X Tailwind plugin that represent a design system builder. With this package you are able to create a design system through a cofiguration file

How to contribute

Report Bugs

Bugs are tracked as GitHub issues.

You can create an issue by filling in the Bug Report template. Before creating a new bug issue, do a quick check to make sure the issue hasn’t been discussed or created before in the project.

Note: If you find a closed issue that seems to describe the same situation as that you're experiencing, open a new issue and include a link to the original issue in the body.

Suggest new features or enhancements

We’d love to hear your suggestions for enhancements for Interface X, whether they are completely new features or minor improvements to existing functionality.

To suggest any new feature, file a new issue using the Feature Request template.

Contribute code for the first time

Unsure where to start with Interface X? You can start by looking through these beginner and help-wanted issues:

  • Beginner issues - issues that should only require a few lines of code, and a test or two.
  • Help wanted issues - issues that are usually a bit more involved than beginner issues.

Both issue lists are sorted by the total number of comments. While not perfect, the number of comments is a reasonable proxy for determining the impact that a given change will have.

Set up your development environment

This monorepo is handled by Lerna using npm. To prepare your development environment, proceed as follows:

  1. Fork the X repo and then clone it to your local environment: git clone https://github.com/empathyco/x.git.
  2. Install the dependencies in the root folder: pnpm install --frozen-lockfile. This links all the projects.
  3. Run a build so that the linked projects work: npm run build.

Pull requests

There are a number of steps must follow to have your contribution considered by the repo maintainers. All pull requests (PRs) must be approved by 2 reviewers to be merged into the project:

  1. Keep your PRs small - don’t pack multiple changes into the same PR.
  2. Perform a self-review before submitting your PR:
    • Create a draft PR and do a full review yourself — complete with comments, docs, and tasks. After finishing a piece of code, it's very tempting to just dump your changes in a PR and let other people find the mistakes (particularly if it is a larger change that took a few days). Don’t be lazy — be disciplined; your work is not over yet.
    • You can also use this “self-review” to point things out to your reviewers — “I’m not sure about this name? Can you think of a better one?”, “Should this really be nullable? What do you think?” — Often by writing such questions, you actually find you can answer them yourself and self-reflection becomes part of your everyday coding thought process. In other words, internalizing this self-review process makes you a better developer.
  3. Follow all instructions given in the PR template.
  4. Follow the style guides.
  5. After you submit your PR, verify that all status checks are passing.
  6. Acknowledge and respond to each and every comment.

Style guides

Git commit messages

Please check the commit section, based on the Conventional Commits specification.

JavaScript style guide

All JavaScript code is linted using the @empathyco/eslint-plugin-x package.

In addition, follow the naming guide in every package inside this project, and the Vue components style guide for components.

Testing style guide

Follow our testing style guide.

Documentation style guide

Use JsDoc tags. For more information, see JsDoc documentation.

Any questions?

If you have a question or doubts about the project, you can contact us at [email protected].

License

By contributing your code, you agree to license your contribution under the terms of the APLv2: https://www.apache.org/licenses/LICENSE-2.0

All files are released with the Apache 2.0 license.