Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
399 lines (282 loc) · 12.6 KB

CONTRIBUTING.md

File metadata and controls

399 lines (282 loc) · 12.6 KB

Contributing to YASGUI

Thank you for your interest in contributing to YASGUI! We welcome contributions from the community to make YASGUI better for everyone.

This document provides guidelines for contributing to YASGUI, including information about our development process, coding standards, and particularly important information about plugin development.

Table of Contents

Code of Conduct

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

Getting Started

Prerequisites

  • Node.js: v20 LTS or higher
  • npm: v10 or higher
  • Git: For version control

Setting Up Your Development Environment

  1. Fork the Repository

    Click the "Fork" button on the YASGUI GitHub repository to create your own fork.

  2. Clone Your Fork

    git clone https://github.com/YOUR-USERNAME/Yasgui.git
cd Yasgui

  3. Install Dependencies

    PUPPETEER_SKIP_DOWNLOAD=1 npm ci

    Note: We use PUPPETEER_SKIP_DOWNLOAD=1 to skip downloading Chromium during installation.

  4. Build the Project

    npm run build

    This compiles TypeScript and bundles all packages. Build time is typically ~5 seconds.

  5. Start the Development Server

    npm run dev

    Visit http://localhost:4000 to see YASGUI in action with hot module reloading.

Plugin Development Policy

IMPORTANT: This section describes our policy for plugin contributions.

Core Philosophy: Separation of Concerns

YASGUI follows a strict plugin development policy to maintain a clean, maintainable codebase:

🚫 Do NOT Add New Plugins to This Repository

New plugins should be created in their own separate repositories. This policy ensures:

  • Clean codebase: The core YASGUI repository stays focused on core functionality
  • Separation of concerns: Each plugin manages its own lifecycle, tests, dependencies, and releases
  • Independent versioning: Plugins can be versioned and released independently
  • Easier maintenance: Plugin maintainers have full control over their code
  • Better modularity: Users can choose which plugins to install

✅ Core Plugins (Keep As-Is)

The following core plugins remain in the repository and should not be modified unless fixing bugs or making necessary improvements:

  • packages/yasr/src/plugins/boolean/ - ASK query results (true/false)
  • packages/yasr/src/plugins/error/ - Error message display
  • packages/yasr/src/plugins/response/ - Raw response viewer

These are essential plugins that are tightly integrated with the core YASR functionality.

📦 External Plugin Examples

Our ecosystem already includes successful external plugins that serve as excellent examples:

🔧 Creating Your Own Plugin

If you want to create a new plugin:

  1. Create a separate repository (e.g., yasr-my-custom-plugin)
  2. Follow the plugin interface documented in our Developer Guide - Plugin Development
  3. Manage your own:
    • Dependencies
    • Tests
    • Documentation
    • Releases
    • Issues
  4. Publish to npm for easy installation by users
  5. Share with the community by mentioning it in GitHub Discussions
Plugin Requirements

All plugins must implement the following requirements:

📚 Help Reference & Download Functionality

  • helpReference: Provide a URL to documentation/help page for your plugin
  • download(): Implement download functionality to allow users to export results in appropriate formats

📐 Responsive Design

  • Utilize 100% of available width and height of the parent element
  • Define minimum usable dimensions when applicable (e.g., minimum width/height for proper visualization)
  • Respond to layout changes: Support both vertical and horizontal orientations when the layout changes
  • Handle resize events: Redraw or adjust visualization when container size changes

🎨 Theme Support

  • Implement both dark and light mode support
  • Use CSS custom properties for colors (e.g., --yasgui-bg-primary, --yasgui-text-primary)
  • Watch for theme changes using MutationObserver on document.documentElement
  • Smooth transitions between themes for better user experience

For detailed plugin development instructions and code examples, see the Developer Guide - Plugin Development section.

Development Workflow

Creating a Feature or Bug Fix

  1. Create a feature branch from main:

    git checkout -b feature/my-feature
# or
git checkout -b fix/my-bugfix

  2. Make your changes following our Code Guidelines

  3. Test your changes:

    # Build first (required before testing)
npm run build

# Run all tests
npm test

# Or run specific test types
npm run unit-test      # Unit tests only (works without Chrome)
npm run puppeteer-test # E2E tests (requires Chrome)

  4. Lint and format your code:

    npm run util:lint      # ESLint check
npm run util:validateTs # TypeScript type checking
npm run util:prettify  # Auto-format with Prettier

    Note: Pre-commit hooks will automatically format staged files.

  5. Commit your changes using Conventional Commits:

    git commit -m "feat: add new feature"
git commit -m "fix: resolve issue with query execution"
git commit -m "docs: update API documentation"

    Commit types: feat, fix, docs, style, refactor, test, chore

  6. Push to your fork:

    git push origin feature/my-feature

  7. Create a Pull Request on GitHub

Code Guidelines

TypeScript

  • Use TypeScript for all new code
  • Follow existing patterns in the codebase
  • Define proper types - avoid any when possible
  • Export types that are part of the public API
  • Document complex types with JSDoc comments

Code Style

  • 2 spaces for indentation (enforced by Prettier)
  • Semicolons are required
  • Single quotes for strings
  • Trailing commas in multi-line objects/arrays
  • ESLint rules must pass (run npm run util:lint)

CSS/SCSS

  • Use CSS custom properties for theming
  • Support both light and dark themes
  • Follow BEM naming when appropriate
  • Keep specificity low - avoid deeply nested selectors
  • Use existing CSS variables:
    • --yasgui-bg-primary, --yasgui-bg-secondary, --yasgui-bg-tertiary
    • --yasgui-text-primary, --yasgui-text-secondary
    • --yasgui-accent-color, --yasgui-border-color

Example:

.my-component {
  background: var(--yasgui-bg-primary);
  color: var(--yasgui-text-primary);
  border: 1px solid var(--yasgui-border-color);
  transition: background-color 0.3s ease, color 0.3s ease;
}

Documentation

  • Update documentation when changing behavior
  • Add JSDoc comments for public APIs
  • Include examples for complex features
  • Update README if adding major features

Testing

Build Before Testing

Always build before running tests - tests require compiled output:

npm run build
npm test

Test Types

  • Unit Tests: Test individual functions and components

    npm run unit-test

  • E2E Tests: Test the full application (requires Chrome)

    npm run puppeteer-test

Writing Tests

  • Test files should end with -test.ts or .test.ts
  • Use Mocha and Chai (existing test framework)
  • Follow existing test patterns in the test/ directory
  • Test both success and error cases
  • Keep tests focused - one concept per test

Example test structure:

import { expect } from 'chai';
import MyClass from '../src/MyClass';

describe('MyClass', () => {
  it('should do something correctly', () => {
    const instance = new MyClass();
    const result = instance.doSomething();
    expect(result).to.equal('expected value');
  });
});

Pull Requests

Before Submitting

  • ✅ Build succeeds: npm run build
  • ✅ All tests pass: npm test
  • ✅ Linting passes: npm run util:lint
  • ✅ Type checking passes: npm run util:validateTs
  • ✅ Code is formatted: npm run util:prettify (or rely on pre-commit hooks)
  • ✅ Documentation updated (if applicable)
  • ✅ Commits follow conventional format

PR Description

Include in your pull request:

  1. Description of what the PR does
  2. Issue reference (if applicable): "Fixes #123" or "Closes #456"
  3. Testing performed - how you verified the changes
  4. Screenshots (if UI changes)
  5. Breaking changes (if any)

Review Process

  1. Automated checks run on all PRs (GitHub Actions)
  2. Code review by maintainers
  3. Feedback addressed through additional commits
  4. Approval and merge by maintainers

PR Best Practices

  • Keep PRs focused - one feature or fix per PR
  • Small is better - easier to review and merge
  • Respond to feedback promptly and constructively
  • Rebase if needed to keep history clean (if requested)

Reporting Issues

Bug Reports

When reporting a bug, include:

  • Environment: Browser version, OS, Node.js version (if relevant)
  • Steps to reproduce: Detailed steps to trigger the bug
  • Expected behavior: What you expected to happen
  • Actual behavior: What actually happened
  • Console errors: Any error messages from browser console
  • Sample query: A minimal SPARQL query that demonstrates the issue

Use the GitHub issue template if available.

Feature Requests

When requesting a feature:

  • Use case: Explain why this feature is needed
  • Proposed solution: Describe how you envision it working
  • Alternatives: Mention any alternative approaches you've considered
  • Willingness to implement: Let us know if you're willing to work on it

Community

Getting Help

Communication Guidelines

  • Be respectful and considerate
  • Search existing issues/discussions before posting
  • Provide context and details
  • Stay on topic
  • Help others when you can

Project Structure

For reference, here's the repository structure:

Yasgui/
├── packages/               # Monorepo packages (source code)
│   ├── yasgui/            # Main package - integrates yasqe + yasr
│   ├── yasqe/             # Query editor (CodeMirror-based)
│   ├── yasr/              # Results viewer with plugin system
│   │   └── src/plugins/   # ⚠️ CORE PLUGINS ONLY - Keep as-is
│   └── utils/             # Shared utilities
├── build/                 # Build output (gitignored)
├── dev/                   # Development HTML pages for testing
├── test/                  # Test files
├── docs/                  # Markdown documentation
├── .github/workflows/     # CI/CD pipelines
└── CONTRIBUTING.md        # This file

Additional Resources

Questions?

If you have questions about contributing, please:

  1. Check the Developer Guide
  2. Search GitHub Discussions
  3. Open a new discussion if your question isn't answered

Thank you for contributing to YASGUI! 🎉