Onboarding

The redesigned VTEX Admin is a collaborative effort. We want to make contributing to this project as easy and transparent as possible, and this document aims to guide you through the process.

If you are a VTEXer, and your questions were not clarified here, feel free to reach us through slack at #dev-design-system. Follow the steps below to contribute to our redesigned VTEX Admin's development.

Tools and conventions

Issues: where the conversation happens

We are using GitHub Issues for our public bugs, new features, and discussions. We keep a close eye on them and try to make it clear when we have an internal fix or feature in progress. Feel free to create new issues and open discussions about anything that you think is relevant to the project. However, before filing a new task, make sure your issue does not already exist.

Storybook

We use storybook as a canvas to create stories and as a preview of our components' features. It is really useful to share with the designers and check if the component has the expected behavior.

Commit messages

It is essential that all commits follow an established convention. We ask you to please take the time to understand semantic versioning before committing.

• Tools: we use commitlint and commitizen to automate enforcement of Conventional Commits.
• Messages: as a shorthand, we always use the git cz command to ensure that we are following our commitlint.

Development Workflow

Follow the instructions below to get started on development with Admin UI.

Getting started

1. Clone the repository vtex/admin-ui.
2. Run yarn to fetch its dependencies.
3. Run commands of your choosing.
4. Run yarn test.

Scripts

Check out the list of scripts available for getting started with Admin UI:

Command	Description
yarn build	Builds the entire repository and its packages
yarn test	Runs the complete test suite
yarn lint	Checks the code style
yarn docs	Runs the documentation site locally
yarn build:docs	Builds the documentation site
yarn storybook	Runs the storybook locally
yarn buid:storybook	Builds storybook
yarn commit	Runs the git-cz cli

Your First Pull Request

To help you get your feet wet and get you familiar with our contribution process, we have a list of good first issues that contain bugs that have a relatively limited scope. This is a great place to get started.

If you decide to fix an issue, please be sure to check the comment thread in case somebody is already working on a fix. If nobody is working on it at the moment, please leave a comment, and assign yourself to the issue, stating that you intend to work on it so other people don’t accidentally duplicate your effort.

Sending a Pull Request

The core team is monitoring for pull requests. We will review your pull request and either merge it, request changes to it, or close it with an explanation. We’ll do our best to provide updates and feedback throughout the process.

Before submitting a pull request:, please make sure the following is done:

1. Clone the repository and create your branch from main.
2. Run yarn: in the repository root.
3. If you have fixed a bug or added code that should be tested, add tests.
4. If you have created a new component or added a new feature, add stories in the storybook.
5. Ensure the test suite passes (yarn test).
6. Format your code with prettier (yarn prettier).
7. Make sure your code lints (yarn lint).
8. Run yarn build, yarn build:storybook or yarn build:site to ensure that the builds are still working.

Contributing with documentation

Our Admin UI documentation is constantly updated and improved to support you in your journey with the VTEX design system. And to make this a collaborative effort, check out how to contribute with our documentation in the sections below.

Editing a page

Our documentation site is built using Docusaurus, a static website generator. All of our documentation is stored in the /docs folder of our Github Repository.

To edit any page in the Admin UI website:

1. In the selected page, click on the Edit this page button that appears at the bottom. You will be redirected to the page on our Admin UI Github Repository.
2. In the Edit file space, make the desired changes to our documentation. Note that we use Markdown in our files to make editing accessible.
3. Select the option Create a new branch for this commit and start a pull request.
4. Add comments to your Pull Request.
5. Click on Propose changes.

We will review your Pull request and update our documentation accordingly!

If using Github is not really your thing, you can also contribute to our documentation by creating an issue in our repository. Learn more about how to create an issue on Github.

Guidelines for writing documentation

Keep the following recommendations in mind when editing our documentation, so we can create a consistent documentation experience for users all around the world:

• Regardless of what you are writing about, you must always aim for the following goals:
  • Clarity: make sure your content is free from any possible ambiguities.
  • Precision: stick to the main message you want to communicate and cut everything else.
• Be concise. Yes, documentation is where you add more context about a project, but be careful when creating docs that are too long to read.
• Use Markdown formatting to make your documentation scannable when users skim through it. Avoid walls of text.
• Prefer direct, informative and clear language, written specifically for an identified audience.
• Be gender neutral. Avoid gender-specific pronouns such as he or she, and prefer the non-binary pronoun they when referring to a singular person.
• Prefer active voice instead of passive voice. In the active voice, the subject of the sentence performs the action, instead of being acted upon. That's because in documentation it's essential that the reader clearly understands who or what is responsible for each action.