Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
494 lines (369 loc) · 13.3 KB

CONTRIBUTING.md

File metadata and controls

494 lines (369 loc) · 13.3 KB

Contributing to FossFLOW

Thank you for your interest in contributing to FossFLOW! This guide will help you get started with contributing to the project.

Table of Contents

Project Scope

FossFLOW is a simple, privacy-first, browser-based isometric diagramming tool. It deliberately avoids enterprise complexity.

The following are out of scope and PRs implementing them will be closed immediately:

  • Authentication, RBAC, OIDC, SSO, or any identity management
  • User accounts, teams, or multi-tenancy
  • Cloud hosting, SaaS features, or paid tiers
  • Database integrations
  • Anything that fundamentally changes what FossFLOW is

If you're unsure whether your idea fits, open a Discussion first.

Code of Conduct

By participating in this project, you agree to abide by our Code of Conduct:

  • Be respectful: Treat everyone with respect. No harassment, discrimination, or inappropriate behavior.
  • Be collaborative: Work together to resolve conflicts and assume good intentions.
  • Be patient: Remember that everyone has different levels of experience.
  • Be welcoming: Help new contributors feel welcome and supported.

Getting Started

Prerequisites

  • Node.js (v18 or higher)
  • npm (v9 or higher)
  • Git
  • A code editor (VS Code recommended)
  • Docker (optional, for containerized deployment)

Quick Start

  1. Fork the repository on GitHub
  2. Clone your fork: 
    git clone https://github.com/YOUR_USERNAME/FossFLOW.git
cd FossFLOW
  3. Install dependencies: 
    npm install
  4. Build the library: 
    npm run build:lib
  5. Start the development server: 
    npm run dev
  6. Open http://localhost:3000 in your browser

Development Setup

IDE Setup (VS Code)

Recommended extensions:

  • ESLint
  • Prettier
  • TypeScript and JavaScript Language Features

Environment Setup

  1. Install dependencies:

    npm install

  2. Available scripts:

    npm run dev          # Start app development server
npm run dev:lib      # Watch mode for library development
npm run build        # Build both library and app
npm run build:lib    # Build library only
npm run build:app    # Build app only
npm test             # Run tests
npm run lint         # Check for linting errors
npm run publish:lib  # Publish library to npm

Project Structure

This is a monorepo containing two packages:

FossFLOW/
├── packages/
│   ├── fossflow-lib/     # React component library
│   │   ├── src/
│   │   │   ├── components/    # React components
│   │   │   ├── stores/        # State management (Zustand)
│   │   │   ├── hooks/         # Custom React hooks
│   │   │   ├── interaction/   # User interaction handling
│   │   │   ├── types/         # TypeScript types
│   │   │   └── utils/         # Utility functions
│   │   ├── rslib.config.ts # Library build config
│   │   └── package.json
│   │
│   └── fossflow-app/      # PWA application
│       ├── src/
│       │   ├── App.tsx         # Main app component
│       │   ├── diagramUtils.ts # Diagram utilities
│       │   └── index.tsx       # App entry point
│       ├── public/            # Static assets
│       ├── rsbuild.config.ts  # App build config
│       └── package.json
│
├── Dockerfile             # Docker configuration
├── compose.yml           # Docker Compose config
├── package.json          # Root workspace config
└── tsconfig.base.json    # Shared TypeScript config

Key Differences:

  • fossflow-lib: The core library, built with RSpack
  • fossflow-app: The PWA application, built with RSBuild
  • Both packages are managed as npm workspaces

How to Contribute

Finding Issues to Work On

  1. Check the Issues page
  2. Look for issues labeled:
    • good first issue - Great for newcomers
    • help wanted - Community help needed
    • bug - Bug fixes
    • enhancement - New features
  3. Check FOSSFLOW_TODO.md for prioritized tasks

Types of Contributions

We welcome all types of contributions:

  • Bug fixes: Help us squash bugs
  • Features: Implement new functionality
  • Documentation: Improve docs, add examples
  • Tests: Increase test coverage
  • UI/UX improvements: Make FossFLOW better to use
  • Performance: Optimize code for better performance

Development Workflow

Working with the Monorepo

Library Development (fossflow-lib)

# Start library in watch mode
npm run dev:lib

# Build library
npm run build:lib

# Run library tests
cd packages/fossflow-lib && npm test

App Development (fossflow-app)

# Start app dev server
npm run dev

# Build app for production
npm run build:app

# The app automatically uses the local library

1. Create a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description

Branch naming conventions:

  • feature/ - New features
  • fix/ - Bug fixes
  • docs/ - Documentation updates
  • refactor/ - Code refactoring
  • test/ - Test additions/updates

2. Make Your Changes

  • Write clean, readable code
  • Follow existing patterns in the codebase
  • Add comments for complex logic only
  • Update tests if needed
  • Update documentation if needed
  • Test changes in both library and app if applicable

3. Test Your Changes

# Run all tests
npm test

# Run linting
npm run lint

# Test library changes
npm run build:lib

# Test app with library changes
npm run dev

4. Commit Your Changes

IMPORTANT: We use Conventional Commits with automated semantic versioning. Your commit messages directly control version bumps and changelog generation.

Commit Format

<type>(<scope>): <subject>

[optional body]

[optional footer]

Examples

git commit -m "feat: add undo/redo functionality"
git commit -m "fix: prevent menu from opening during drag"
git commit -m "docs: update installation instructions"
git commit -m "feat(connector)!: change default connector mode to click"

Commit Types

Version-bumping commits:

  • feat: New feature (triggers MINOR version bump, e.g., 1.0.0 → 1.1.0)
  • fix: Bug fix (triggers PATCH version bump, e.g., 1.0.0 → 1.0.1)
  • perf: Performance improvement (triggers PATCH version bump)
  • refactor: Code refactoring (triggers PATCH version bump)

Non-version-bumping commits:

  • docs: Documentation only changes (no version bump)
  • style: Code style changes - formatting, whitespace (no version bump)
  • test: Adding or updating tests (no version bump)
  • chore: Maintenance tasks, dependency updates (no version bump)
  • build: Build system changes (no version bump)
  • ci: CI/CD configuration changes (no version bump)

Breaking changes:

  • Add ! after type/scope OR add BREAKING CHANGE: in footer
  • Triggers MAJOR version bump (e.g., 1.0.0 → 2.0.0)
  • Example: feat!: redesign node selection API

Scopes (optional but recommended)

Common scopes in FossFLOW:

  • connector: Connector-related changes
  • ui: UI components and interactions
  • storage: Storage and persistence
  • export: Export/import functionality
  • docker: Docker and deployment
  • i18n: Internationalization

Breaking Change Examples

# Option 1: Using ! in type
git commit -m "feat(api)!: remove deprecated exportImage function"

# Option 2: Using footer
git commit -m "feat: update node API

BREAKING CHANGE: Node.position is now an object with x,y properties instead of array"

Release Notes

Your commits will automatically generate:

  • Version number based on commit types
  • Changelog with categorized changes
  • GitHub release notes

Coding Standards

TypeScript

  • Use TypeScript for all new code
  • Avoid any types — if unavoidable, leave a comment explaining why
  • Define interfaces for component props
  • Use meaningful variable and function names

Example:

interface NodeProps {
  id: string;
  position: { x: number; y: number };
  icon: IconType;
  isSelected?: boolean;
}

const Node: React.FC<NodeProps> = ({ id, position, icon, isSelected = false }) => {
  // Component implementation
};

React

  • Use functional components with hooks
  • Keep components focused and small
  • Use custom hooks for reusable logic
  • Memoize expensive computations

State Management

  • Use Zustand stores appropriately:
    • modelStore: Business data
    • sceneStore: Visual state
    • uiStateStore: UI state
  • Keep actions pure and predictable

Styling

  • Use Material-UI components when possible
  • Follow existing styling patterns
  • Use theme variables for colors
  • Ensure responsive design

Comments

  • No unnecessary comments. The code should be self-documenting
  • Comments like // This function handles the click event or // Main logic here indicate a lack of understanding and will get your PR closed
  • Only add comments for genuinely complex logic that isn't immediately obvious

AI-Assisted Contributions

AI tools can be useful for writing code. However:

  • You must understand every line of your PR. If asked to explain a section, you should be able to
  • PRs that are clearly generated without human review will be closed without discussion
  • If your PR contains generic AI-generated comments (we can tell), it will be closed
  • "Vibe-coded" PRs are not welcome — if you can't debug it, don't submit it

Testing

Running Tests

npm test                    # Run all tests
npm test -- --watch        # Watch mode
npm test -- --coverage     # Coverage report

Writing Tests

  • Write tests for new features
  • Update tests when changing existing code
  • Test edge cases and error scenarios
  • Use meaningful test descriptions

Example:

describe('useIsoProjection', () => {
  it('should convert tile coordinates to screen coordinates', () => {
    const { tileToScreen } = useIsoProjection();
    const result = tileToScreen({ x: 1, y: 1 });
    expect(result).toEqual({ x: 100, y: 50 });
  });
});

Submitting Changes

Pull Request Process

  1. Update your fork:

    git remote add upstream https://github.com/stan-smith/FossFLOW.git
git fetch upstream
git checkout main
git merge upstream/main

  2. Push your branch:

    git push origin feature/your-feature-name

  3. Create Pull Request:

    • Go to GitHub and create a PR from your branch
    • Fill out the PR template completely
    • Link related issues
    • Add screenshots/GIFs for UI changes
    • Use conventional commit format for your PR title

PR Title Format

PR titles must follow conventional commit format. Non-compliant PRs will be closed:

feat: add undo/redo functionality
fix: prevent menu from opening during drag
docs: update installation instructions
feat(connector)!: change default connector mode

Code Review

  • Be open to feedback
  • Respond to review comments
  • Make requested changes promptly
  • Ask questions if something is unclear

Docker Development

Building and Running with Docker

# Build multi-architecture image
docker buildx build --platform linux/amd64,linux/arm64 -t fossflow:local .

# Run with Docker Compose
docker compose up

# Or pull from Docker Hub
docker run -p 80:80 stnsmith/fossflow:latest

Community

Getting Help

Communication Guidelines

  • Be clear and concise
  • Provide context and examples
  • Search existing issues before creating new ones
  • Use issue templates when available

Recognition

Contributors will be recognized in:

  • The project README
  • Release notes
  • Contributors list on GitHub

License

By contributing to FossFLOW, you agree that your contributions will be licensed under the project's license.

Thank you for contributing to FossFLOW! Your efforts help make this project better for everyone. If you have any questions, don't hesitate to ask in the issues or discussions.

-S