Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
299 lines (210 loc) · 7.18 KB

CONTRIBUTING.md

File metadata and controls

299 lines (210 loc) · 7.18 KB

Contributing to RUXAILAB

Thank you for your interest in contributing to RUXAILAB! This document provides guidelines and instructions for contributing to this open-source usability testing platform.

Table of Contents

Code of Conduct

We are committed to providing a welcoming and inclusive environment for all contributors. Please be respectful and constructive in all interactions.

Getting Started

RUXAILAB is a Vue.js-based platform for usability testing and heuristic evaluation. Before contributing, familiarize yourself with:

Development Setup

Prerequisites

  • Node.js ≤ 24.12.0
  • Python 3.11.8
  • npm (comes with Node.js)
  • Docker (optional, for Firebase Emulators)

Option 1: Docker with Firebase Emulators (Recommended for Local Development)

This approach runs the entire application with Firebase emulators in Docker containers.

  1. Clone the repository

    git clone https://github.com/uramakilab/remote-usability-lab.git
cd remote-usability-lab

  2. Set up environment variables

    cp .env.example .env

    Update .env with the following for local emulator development:

    DEBUG=true
PORT=8000

VUE_APP_FIREBASE_API_KEY=YOUR_API_KEY
VUE_APP_FIREBASE_AUTH_DOMAIN=YOUR_PROJECT_ID.firebaseapp.com
VUE_APP_FIREBASE_STORAGE_BUCKET=YOUR_PROJECT_ID.appspot.com
VUE_APP_FIREBASE_DB_URL=http://localhost:9000
VUE_APP_FIREBASE_PROJECT_ID=YOUR_PROJECT_ID
VUE_APP_FIREBASE_MESSAGING_SENDER_ID=YOUR_SENDER_ID
VUE_APP_FIREBASE_APP_ID=YOUR_APP_ID
VUE_APP_I18N_LOCALE=en
VUE_APP_I18N_FALLBACK_LOCALE=en

  3. Build and run with Docker

    docker compose build
docker compose up

  4. Access the application

Option 2: Production Firebase Setup

For development with a real Firebase project:

  1. Clone and install dependencies

    git clone https://github.com/uramakilab/remote-usability-lab.git
cd remote-usability-lab
npm install

  2. Create Firebase project

    • Go to Firebase Console
    • Create a new project
    • Enable Realtime Database, Firestore, Authentication, and Storage

  3. Configure environment

    • Get your Firebase config from Project Settings
    • Copy .env.example to .env
    • Fill in your Firebase credentials

  4. Run development server

    npm run serve

Contribution Workflow

1. Fork and Clone

Fork the repository and clone your fork:

git clone https://github.com/YOUR_USERNAME/remote-usability-lab.git
cd remote-usability-lab

2. Create a Feature Branch

Branch from develop:

git checkout develop
git pull origin develop
git checkout -b feature/your-feature-name

Branch naming conventions:

  • feature/ - New features
  • fix/ - Bug fixes
  • docs/ - Documentation updates
  • refactor/ - Code refactoring
  • test/ - Adding or updating tests

3. Make Your Changes

  • Write clean, readable code
  • Follow the existing code style
  • Add tests for new functionality
  • Update documentation as needed

4. Commit Your Changes

Use clear, descriptive commit messages:

git add .
git commit -m "feat: add user profile customization"

Commit message format:

  • feat: - New feature
  • fix: - Bug fix
  • docs: - Documentation changes
  • style: - Formatting, missing semicolons, etc.
  • refactor: - Code restructuring
  • test: - Adding tests
  • chore: - Maintenance tasks

5. Push and Create Pull Request

git push origin feature/your-feature-name

Then create a Pull Request on GitHub:

  • Target the develop branch
  • Provide a clear description of your changes
  • Reference any related issues
  • Wait for review and address any feedback

Code Standards

Formatting

We use Prettier for code formatting. Configuration is in .prettierrc.

# Format all files
npm run format

# Check formatting
npm run format:check

Linting

We use ESLint for code quality. Configuration is in eslint.config.mjs.

# Run linter
npm run lint

# Auto-fix issues
npm run lint:fix

Vue.js Best Practices

  • Use Composition API for new components
  • Follow Vue 3 style guide
  • Use Vuetify components consistently
  • Keep components small and focused
  • Use proper prop validation

File Organization

src/
├── app/
│   ├── components/    # Reusable components
│   ├── plugins/       # Vue plugins (Firebase, etc.)
│   ├── router/        # Vue Router configuration
│   └── views/         # Page components
├── features/          # Feature-specific modules
├── shared/            # Shared utilities and constants
└── store/             # State management

Testing

Unit Tests (Jest)

# Run all tests
npm run test:unit

# Run tests in watch mode
npm run test:unit:watch

# Run with coverage
npm run test:unit:coverage

End-to-End Tests (Playwright)

# Run E2E tests
npm run test:e2e

# Run in headed mode (see browser)
npm run test:e2e:headed

Writing Tests

  • Write unit tests for utility functions and components
  • Write E2E tests for critical user flows
  • Aim for good coverage without over-testing
  • Keep tests maintainable and readable

Reporting Issues

Bug Reports

When reporting bugs, please include:

  • Clear title describing the issue
  • Steps to reproduce the bug
  • Expected behavior vs actual behavior
  • Environment details (OS, browser, Node version)
  • Screenshots if applicable
  • Error messages or console logs

Use the Bug Report template

Feature Requests

For feature requests, include:

  • Use case - Why is this feature needed?
  • Proposed solution - How should it work?
  • Alternatives considered - Other approaches you've thought about

Use the Feature Request template

Questions and Discussions

For questions or general discussion, use GitHub Discussions.

Additional Resources

Getting Help

Thank you for contributing to RUXAILAB! 🎉