Skip to content

contributing.md

Latest commit

 

History

History
203 lines (144 loc) · 5.94 KB

contributing.md

File metadata and controls

203 lines (144 loc) · 5.94 KB

Contributing

Thank you for your interest in contributing to WBProp. This document covers development guidelines, coding conventions, and testing practices.

Development Setup

Prerequisites

  • Node.js 20.19+ or 22.12+
  • npm 9+
  • Git

Getting Started

git clone https://github.com/johnsamuelwrites/wbprop.git
cd wbprop
npm install
npm run dev

The development server starts at http://localhost:3000 with hot module replacement.

Project Conventions

TypeScript

  • Strict mode is enabled (strict: true in tsconfig.json)
  • No unused locals or parameters (noUnusedLocals, noUnusedParameters)
  • Use explicit types for function parameters and return values in service layers
  • Use type inference in Vue component <script setup> blocks where types are clear
  • Prefix unused callback parameters with _ (e.g., _event)

Vue Components

  • Use <script setup lang="ts"> for all components
  • Use the Composition API (no Options API)
  • Props are defined with defineProps<T>() using TypeScript interfaces
  • Emits are defined with defineEmits<T>()
  • Keep templates readable -- extract complex logic into computed properties or functions

File Organization

src/
  components/    # Reusable UI components
  composables/   # Vue composables (use* hooks)
  config/        # Static configuration
  router/        # Route definitions
  services/      # Business logic and API communication
  stores/        # Pinia state management
  types/         # TypeScript interfaces and types
  views/         # Page-level components (one per route)

Naming conventions:

  • Components: PascalCase.vue (e.g., ChartCard.vue)
  • Composables: camelCase.ts with use prefix (e.g., useSparqlQuery.ts)
  • Services: kebab-case.ts (e.g., query-builder.ts)
  • Types: kebab-case.ts (e.g., wikibase-config.ts)
  • Tests: *.spec.ts matching the source file name

SPARQL Queries

  • All SPARQL queries are generated by QueryBuilder -- never write raw queries in views or components
  • Queries must be parameterized for multi-instance support
  • Use this.getPrefixes() for prefix declarations
  • Use this.getLabelService() for optional label service clauses
  • Escape user input (search terms) before embedding in queries

Styling

  • Use Vuetify components and utility classes wherever possible
  • Scoped styles with <style scoped> for component-specific CSS
  • Avoid inline styles unless dynamic (e.g., computed heights)
  • The app supports both light and dark themes -- test both

Adding Features

Adding a New Chart Type

  1. Create a component in src/components/charts/
  2. Accept data: ChartDataItem[] as a prop
  3. Use ECharts (via vue-echarts) or D3.js for rendering
  4. Register the component in the relevant view (Dashboard or Statistics)
  5. Wrap it in a <ChartCard> for consistent loading/error/export behavior

Adding a New SPARQL Query

  1. Add the query method to QueryBuilder in src/services/sparql/query-builder.ts
  2. Create a transform function in src/composables/useSparqlQuery.ts
  3. Create a specialized hook (e.g., useMyNewStats()) wrapping useSparqlQuery
  4. Set the enabled callback if the query is instance-specific
  5. Add unit tests in tests/unit/query-builder.spec.ts

Adding a New View

  1. Create the component in src/views/
  2. Add a route in src/router/index.ts with lazy loading: 
    {
  path: '/my-view',
  name: 'my-view',
  component: () => import('@/views/MyView.vue'),
  meta: { title: 'My View' },
}
  3. Add a navigation item in App.vue if it should appear in the sidebar

Adding a New Preset Instance

See configuration.md for the full process.

Testing

Unit Tests

Unit tests use Vitest and are located in tests/unit/.

# Run all tests
npm test

# Run tests in watch mode
npx vitest

# Run with UI
npm run test:ui

What to test:

  • QueryBuilder -- verify generated SPARQL for each instance type
  • QueryCache -- test TTL, eviction, invalidation, persistence
  • Transform functions -- verify binding-to-data mappings
  • Composable logic -- test data flow (may require mocking Pinia stores)

Test conventions:

  • Use describe/it blocks with clear descriptions
  • Group tests by module or class
  • Use vi.useFakeTimers() for time-dependent tests (cache TTL)
  • Avoid testing Vuetify rendering details -- focus on logic

End-to-End Tests

E2E tests use Playwright:

npm run test:e2e

Running the Full CI Check

To simulate what runs in CI locally:

npm run build && npx vitest run

Code Quality

Linting

# Lint and auto-fix
npm run lint

ESLint is configured with:

  • @typescript-eslint/eslint-plugin for TypeScript rules
  • eslint-plugin-vue for Vue template rules

Formatting

# Format all source files
npm run format

Prettier is configured as the formatter. Run it before committing.

Pull Request Guidelines

  1. Branch from the latest master
  2. Keep PRs focused -- one feature or fix per PR
  3. Write tests for new query builder methods and cache logic
  4. Run the full check before submitting: npm run build && npx vitest run
  5. Update documentation if adding new features, configuration options, or views
  6. Follow existing patterns -- look at similar code in the codebase for conventions

Architecture Notes

For a detailed understanding of the codebase before contributing, see architecture.md.

Key design principles:

  • Instance-agnostic by default -- all queries should work across Wikibase instances unless explicitly gated by enabled callbacks
  • Cache-first -- avoid unnecessary network requests; let users manually refresh when needed
  • Graceful degradation -- if a feature is unsupported (e.g., no label service), fall back to a simpler query rather than failing
  • Type safety -- leverage TypeScript to catch errors at compile time; avoid any where possible
⚡