FossFLOW/CONTRIBUTING.md

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
• Code of Conduct
• Getting Started
• Development Setup
• Project Structure
• How to Contribute
• Development Workflow
• Coding Standards
• AI-Assisted Contributions
• Testing
• Submitting Changes
• Community
• Recognition
• License

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

• GitHub Issues: For bugs and feature requests (use the templates)
• Discussions: For questions and ideas
• Code Encyclopedia: See FOSSFLOW_ENCYCLOPEDIA.md
• TODO List: See FOSSFLOW_TODO.md

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