Contribution

A comprehensive guide on contributing to EletroDS, including project structure, development workflow, and best practices.

Mercado Eletrônico and EletroDS grow even more with your initiative to contribute . Your contributions, whether through bug reports, pull requests, or feedback, are essential to continuously improve this library.

Project Structure

EletroDS is organized as a monorepo using pnpm workspaces and Turborepo for efficient package management. Here's an overview of the key directories and files:

// Main entry point for @mercadoeletronico/eds-next
// Exports all components, composables, and utilities

export * from './components'
export * from './useTheme'

Package Overview

Key Directories

Getting Started

Jira Board

We use Jira to manage our development tasks and track progress. All available tasks can be found on our Jira board.

Taking a Task

Validation Template

When you take a task, add the following template as a comment in the Jira task:

✨ For validation

**Component Developed:** [Component Name]
**Link:** [Link to component documentation or example]
**Description:** [Brief description of what was implemented]

**Screenshots/Video:**
[Attach screenshots or video demonstrating the component - required for visual validation]

**Testing:**
- [ ] Cypress tests written and passing
- [ ] Component tested in different scenarios
- [ ] Cross-browser testing completed (if applicable)

**Documentation:**
- [ ] Documentation created/updated following Documentation Guide
- [ ] Examples provided
- [ ] Props, events, and slots documented

Local Development

To begin local development, follow these steps:

git clone <repository-url>
cd me-toolkit

# Using yarn
yarn install

yarn dev

IDE Setup

We recommend using VSCode alongside the ESLint extension. You can enable auto-fix and formatting when saving your code:

{
  "editor.codeActionsOnSave": {
    "source.fixAll": false,
    "source.fixAll.eslint": true
  }
}

Linting

You can use the lint command to check for linting errors:

yarn lint        # check for linting errors

Testing

Before submitting a MR, ensure that you run the tests:

# Run unit tests
yarn test

# Run Cypress component tests
yarn cy

# Open Cypress component tests
yarn cy:open

Writing Cypress Tests

All components should have corresponding Cypress tests. Tests should be located in test/unit/components/ and follow the naming convention [ComponentName].spec.js.

Example test structure:

describe('ComponentName', () => {
  it('should render correctly', () => {
    // Test implementation
  })

  it('should handle user interactions', () => {
    // Test implementation
  })
})

Documentation

Creating Component Documentation

When creating or updating component documentation:

Documentation Structure

Component documentation should follow this structure:

Validation Criteria

Before submitting your work for validation, ensure you meet all the following criteria:

Component Development

Testing Checklist

• Cypress tests are written and passing
• Component is tested in different scenarios
• Tests cover main functionality and edge cases
• Cross-browser testing completed (if applicable)

Documentation Checklist

• Documentation created/updated following the Documentation Guide
• Examples provided and working
• Props, events, and slots are fully documented
• Documentation is clear and easy to understand

Code Quality Checklist

• Code follows project conventions
• ESLint passes without errors
• No console errors or warnings
• Code is properly commented where necessary

Submitting Changes

Commit Conventions

We use Jira commit format for commit messages. All commits must include the Jira task code and time tracking.

Commit Format:

MW-XXXXX #time Xd - commit message

Where:

• MW-XXXXX is the Jira task code
• #time Xd is the time spent (e.g., 2d for 2 days, 4h for 4 hours)
• commit message is a brief description of the changes

Examples:

MW-67130 #time 2d - add new Button component variant
MW-67131 #time 4h - resolve modal closing issue
MW-67132 #time 1d - update Button component documentation
MW-67133 #time 1h - update dependencies

Branch Naming Conventions

Branches must follow the naming pattern based on the type of change:

Making a Merge Request

MR Requirements

• Follow along the instructions provided when creating a MR
• Ensure your MR's title includes the Jira task code and follows the commit format (e.g., MW-67130 #time 2d - description)
• Ensure lint and tests work before submitting the MR
• Avoid making unrelated changes
• Include screenshots or videos if the changes are visual

We'll review it promptly. If assigned to a maintainer, they'll review it carefully.

Thanks