Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
156 lines (108 loc) · 4.28 KB

CONTRIBUTING.md

File metadata and controls

156 lines (108 loc) · 4.28 KB
Raw

Contributing to oui-kit

Thank you for your interest in contributing to oui-kit! This guide will help you understand our development workflow, coding standards, and best practices.

General Structure

This project has the following main products:

  1. A Vue3 component library (oui-kit), source code is located in the lib folder.
  2. A Stylus CSS framework (oui-kit), source code is located in the stylus folder.
  3. A demo application to showcase the components and framework, source code is located in the src folder.

Development Setup

  1. Clone the repository
  2. Install dependencies: pnpm install
  3. Start development server: pnpm start

Coding Standards

File Structure and Naming

  • Test files: Always end with .spec.ts and are located in the same folder as the file being tested
  • Component files: Use kebab-case for Vue components (e.g., oui-component.vue)
  • Utility files: Use camelCase for utility functions and modules

Code Style

Code formatting and style rules are automatically enforced through:

  • .editorconfig - Handles basic formatting (indentation, line endings, etc.)
  • ESLint - Enforces code quality and style rules

Make sure your editor supports these tools and has the appropriate extensions installed:

  • EditorConfig extension for your editor
  • ESLint extension for your editor
  • Configure your editor to format on save

Key Style Guidelines

  • Indentation: 2 spaces (enforced by .editorconfig)
  • Component files: Use kebab-case for Vue components (e.g., oui-component.vue)

Vue 3 Development

Composition API

  • Always use Vue 3 with Composition API (not Options API)
  • Import components automatically when used
  • Use <script setup> syntax for cleaner code

Logging

Use the zeed module for all logging needs:

// ✅ Correct logging setup
import { Logger, LoggerInterface } from 'zeed'

// Filename without suffix (e.g., for OuiComponent.ts use "oui-component")
const log: LoggerInterface = Logger('oui-component')

Logging Best Practices

  • Use appropriate log levels: debug, info, warn, error
  • Include relevant context in log messages
  • Use structured logging with objects for additional data
  • Logger name should match the filename without extension

Testing

Demo

A custom sanbox like environment is available for testing components. All files matching the pattern *.demo.vue will be automatically loaded and displayed in the demo environment.

Simple examples:

<script lang="ts" setup>
import { reactive } from 'vue'
import { OuiCheckbox, OuiDemo } from '../lib'

const state = reactive({
  value: false,
  disabled: false
})
</script>

<template>
  <div>
    <OuiCheckbox v-model="state.value" :disabled="disabled" />
    Just a switch
  </div>

  <OuiDemo :state="state">
    <OuiCheckbox v-model="state.disabled" title="Disabled" />
  </OuiDemo>
</template>

Git Workflow

Commit Messages

All commit messages should:

  • Be lowercase
  • Start with one of these prefixes:
    • feat: - New features
    • fix: - Bug fixes
    • chore: - Maintenance tasks
# ✅ Correct commit messages
git commit -m "feat: add user authentication component"
git commit -m "fix: resolve memory leak in data service"
git commit -m "chore: updated dependencies"

# ❌ Incorrect commit messages
git commit -m "Add user auth"  # Missing prefix, not lowercase
git commit -m "Fixed bug"      # Not descriptive enough

Special Cases

  • If only package.json has been updated: chore: updated dependencies

Code Review Guidelines

Before Submitting a PR

  • Code follows all style guidelines
  • Tests are written and passing
  • Logging is implemented where appropriate
  • Documentation is updated if needed
  • Commit messages follow the convention
  • No console.log statements (use proper logging)

Review Checklist

  • Code style and formatting
  • Test coverage and quality
  • Performance considerations
  • Security implications
  • Documentation completeness
  • Accessibility compliance (for UI components)

Getting Help

  • Check existing issues and documentation
  • Ask questions in discussions
  • Follow the coding standards outlined in this guide
  • When in doubt, look at existing code for patterns and examples

Thank you for contributing to make oui-kit better! 🚀