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!
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].
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 search client for Empathy's Search API.
- @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.
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.
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.
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
beginnerissues.
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.
This monorepo is handled by Lerna using npm. To prepare your
development environment, proceed as follows:
- Fork the X repo and then clone it to your local environment:
git clone https://github.com/empathyco/x.git. - Install the dependencies in the root folder:
npm install. This links all the projects. - Run a build so that the linked projects work:
npm run build.
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:
- Keep your PRs small - don’t pack multiple changes into the same PR.
- 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.
- Follow all instructions given in the PR template.
- Follow the style guides.
- After you submit your PR, verify that all status checks are passing.
- Acknowledge and respond to each and every comment.
Please check the commit section, based on the Conventional Commits specification.
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.
Follow our testing style guide.
Use JsDoc tags. For more information, see JsDoc documentation.
If you have a question or doubts about the project, you can contact us at [email protected].
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.