chore: added code of conduct, security guidelines. updated issue templates, CONTRIBUTING, README

2026-01-07 22:24:06 -05:00 · 2025-03-16 15:20:27 -07:00
parent 7017cd4629
commit 622e05a430
7 changed files with 211 additions and 74 deletions
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -0,0 +1,455 @@
+# Contributing to Sim Studio
+
+Thank you for your interest in contributing to Sim Studio! Our goal is to provide developers with a powerful, user-friendly platform for building, testing, and optimizing agentic workflows. We welcome contributions in all forms—from bug fixes and design improvements to brand-new features.
+
+> **Project Overview:**  
+> Sim Studio is a monorepo containing the main application (`sim/`) and documentation (`docs/`). The main application is built with Next.js (app router), ReactFlow, Zustand, Shadcn, and Tailwind CSS. Please ensure your contributions follow our best practices for clarity, maintainability, and consistency.
+
+---
+
+## Table of Contents
+
+- [How to Contribute](#how-to-contribute)
+- [Reporting Issues](#reporting-issues)
+- [Pull Request Process](#pull-request-process)
+- [Commit Message Guidelines](#commit-message-guidelines)
+- [Local Development Setup](#local-development-setup)
+- [License](#license)
+- [Adding New Blocks and Tools](#adding-new-blocks-and-tools)
+- [Local Storage Mode](#local-storage-mode)
+- [Standalone Build](#standalone-build)
+
+---
+
+## How to Contribute
+
+We strive to keep our workflow as simple as possible. To contribute:
+
+1. **Fork the Repository**  
+   Click the **Fork** button on GitHub to create your own copy of the project.
+
+2. **Clone Your Fork**
+   ```bash
+   git clone https://github.com/<your-username>/sim.git
+   ```
+3. **Create a Feature Branch**  
+   Create a new branch with a descriptive name:
+
+   ```bash
+   git checkout -b feat/your-feature-name
+   ```
+
+   Use a clear naming convention to indicate the type of work (e.g., `feat/`, `fix/`, `docs/`).
+
+4. **Make Your Changes**  
+   Ensure your changes are small, focused, and adhere to our coding guidelines.
+
+5. **Commit Your Changes**  
+   Write clear, descriptive commit messages that follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#specification) specification. This allows us to maintain a coherent project history and generate changelogs automatically. For example:
+   - `feat(api): add new endpoint for user authentication`
+   - `fix(ui): resolve button alignment issue`
+   - `docs: update contribution guidelines`
+6. **Push Your Branch**
+
+   ```bash
+   git push origin feat/your-feature-name
+   ```
+
+7. **Create a Pull Request**  
+   Open a pull request against the `main` branch on GitHub. Please provide a clear description of the changes and reference any relevant issues (e.g., `fixes #123`).
+
+---
+
+## Reporting Issues
+
+If you discover a bug or have a feature request, please open an issue in our GitHub repository. When opening an issue, ensure you:
+
+- Provide a clear, descriptive title.
+- Include as many details as possible (steps to reproduce, screenshots, etc.).
+- **Tag Your Issue Appropriately:**  
+  Use the following labels to help us categorize your issue:
+  - **active:** Actively working on it right now.
+  - **bug:** Something isn't working.
+  - **design:** Improvements & changes to design & UX.
+  - **discussion:** Initiate a discussion or propose an idea.
+  - **documentation:** Improvements or updates to documentation.
+  - **feature:** New feature or request.
+
+> **Note:** If you're uncertain which label to use, mention it in your issue description and we'll help categorize it.
+
+---
+
+## Pull Request Process
+
+Before creating a pull request:
+
+- **Ensure Your Branch Is Up-to-Date:**  
+  Rebase your branch onto the latest `main` branch to prevent merge conflicts.
+- **Follow the Guidelines:**  
+  Make sure your changes are well-tested, follow our coding standards, and include relevant documentation if necessary.
+
+- **Reference Issues:**  
+  If your PR addresses an existing issue, include `refs #<issue-number>` or `fixes #<issue-number>` in your PR description.
+
+Our maintainers will review your pull request and provide feedback. We aim to make the review process as smooth and timely as possible.
+
+---
+
+## Commit Message Guidelines
+
+We follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#specification) standard. Your commit messages should have the following format:
+
+```
+<type>[optional scope]: <description>
+```
+
+- **Types** may include:
+  - `feat` – a new feature
+  - `fix` – a bug fix
+  - `docs` – documentation changes
+  - `style` – code style changes (formatting, missing semicolons, etc.)
+  - `refactor` – code changes that neither fix a bug nor add a feature
+  - `test` – adding or correcting tests
+  - `chore` – changes to tooling, build process, etc.
+  - `high priority` – a high priority feature or fix
+  - `high risk` – a high risk feature or fix
+  - `improvement` – an improvement to the codebase
+
+_Examples:_
+
+- `feat[auth]: add social login integration`
+- `fix[ui]: correct misaligned button on homepage`
+- `docs: update installation instructions`
+
+Using clear and consistent commit messages makes it easier for everyone to understand the project history and aids in automating changelog generation.
+
+---
+
+## Local Development Setup
+
+To set up your local development environment:
+
+### Option 1: Using Docker (Recommended)
+
+Docker provides a consistent development environment with all dependencies pre-configured.
+
+1. **Clone the Repository:**
+
+   ```bash
+   git clone https://github.com/<your-username>/sim.git
+   cd sim
+   ```
+
+2. **Start the Docker Environment:**
+
+   ```bash
+   docker compose up -d
+   ```
+
+   Or use the convenience script which handles environment setup and migrations:
+
+   ```bash
+   chmod +x scripts/start_simstudio_docker.sh
+   ./scripts/start_simstudio_docker.sh
+   ```
+
+   This will:
+
+   - Start a PostgreSQL database container
+   - Build and run the Next.js application with hot-reloading
+   - Set up all necessary environment variables
+   - Apply database migrations automatically
+
+3. **View Logs:**
+
+   ```bash
+   docker compose logs -f simstudio
+   ```
+
+4. **Make Your Changes:**
+   - Edit files in your local directory
+   - Changes will be automatically reflected thanks to hot-reloading
+
+### Option 2: Using VS Code / Cursor Dev Containers
+
+Dev Containers provide a consistent and easy-to-use development environment:
+
+1. **Prerequisites:**
+
+   - Visual Studio Code
+   - Docker Desktop
+   - [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension for VS Code
+
+2. **Setup Steps:**
+   - Clone the repository:
+     ```bash
+     git clone https://github.com/<your-username>/sim.git
+     cd sim
+     ```
+   - Open the project in VS Code
+   - When prompted, click "Reopen in Container" (or press F1 and select "Remote-Containers: Reopen in Container")
+   - Wait for the container to build and initialize
+   - The development environment will be set up in the `sim/` directory
+
+3. **Start Developing:**
+
+   - All dependencies and configurations are automatically set up
+   - Use the provided aliases (like `sim-start`) to run common commands
+   - Your changes will be automatically hot-reloaded
+
+4. **GitHub Codespaces:**
+   - This setup also works with GitHub Codespaces if you prefer development in the browser
+   - Just click "Code" → "Codespaces" → "Create codespace on main"
+
+### Option 3: Manual Setup
+
+If you prefer not to use Docker or Dev Containers:
+
+1. **Clone the Repository:**
+   ```bash
+   git clone https://github.com/<your-username>/sim.git
+   cd sim/sim
+   ```
+2. **Install Dependencies:**
+
+   - Using NPM:
+     ```bash
+     npm install
+     ```
+
+3. **Set Up Environment:**
+
+   - Copy `.env.example` to `.env`
+   - Configure database connection and other required authentication variables
+
+4. **Set Up Database:**
+
+   - You need a PostgreSQL instance running
+   - Run migrations:
+     ```bash
+     npm run db:push
+     ```
+
+5. **Run the Development Server:**
+
+   - With NPM:
+     ```bash
+     npm run dev
+     ```
+
+6. **Make Your Changes and Test Locally.**
+
+---
+
+## License
+
+This project is licensed under the MIT License. By contributing, you agree that your contributions will be licensed under the MIT License as well.
+
+---
+
+## Adding New Blocks and Tools
+
+Sim Studio is built in a modular fashion where blocks and tools extend the platform's functionality. To maintain consistency and quality, please follow the guidelines below when adding a new block or tool.
+
+### Where to Add Your Code
+
+- **Blocks:** Create your new block file under the `/sim/blocks/blocks` directory.
+- **Tools:** Create your new tool file under the `/sim/tools` directory.
+
+In addition, you will need to update the registries:
+
+- **Block Registry:** Update the blocks index (usually `/sim/blocks/index.ts`) to include your new block.
+- **Tool Registry:** Update the tools registry (`/sim/tools/index.ts`) to add your new tool.
+
+### How to Create a New Block
+
+1. **Create a New File:**  
+   Create a file for your block (e.g., `newBlock.ts`) in the `/sim/blocks/blocks` directory.
+
+2. **Create a New Icon:**
+   Create a new icon for your block in the `/sim/components/icons.tsx` file.
+
+3. **Define the Block Configuration:**  
+   Your block should export a constant of type `BlockConfig`. For example:
+
+   ```typescript:/sim/blocks/blocks/newBlock.ts
+   import { SomeIcon } from '@/components/icons'
+   import { BlockConfig } from '../types'
+
+   // Define response type if needed
+   interface NewBlockResponse {
+     output: {
+       // Define expected output here
+       result: string
+     }
+   }
+
+   export const NewBlock: BlockConfig<NewBlockResponse> = {
+     type: 'new',
+     name: 'New Block',
+     description: 'Description of the new block',
+     longDescription: 'A more detailed description of what this block does and how to use it.',
+     category: 'tools',
+     bgColor: '#123456',
+     icon: SomeIcon,
+
+     // If this block requires OAuth authentication
+     provider: 'new-service',
+
+     // Define subBlocks for the UI configuration
+     subBlocks: [
+       {
+         id: 'apiKey',
+         title: 'API Key',
+         type: 'short-input',
+         layout: 'full',
+         placeholder: 'Enter your API key',
+       },
+       {
+         id: 'query',
+         title: 'Query',
+         type: 'long-input',
+         layout: 'full',
+         placeholder: 'Enter your search query',
+       },
+       {
+         id: 'model',
+         title: 'Model',
+         type: 'dropdown',
+         layout: 'half',
+         options: ['model-1', 'model-2', 'model-3'],
+       },
+     ],
+   }
+   ```
+
+4. **Register Your Block:**  
+   Import and add your block to the blocks registry (`/sim/blocks/index.ts`) in the appropriate index file so it appears in the workflow builder.
+
+   ```typescript:/sim/blocks/index.ts
+   import { NewBlock } from './blocks/newBlock'
+
+   export const blocks = [
+     // ... existing blocks
+     NewBlock,
+   ]
+
+   export const blocksByType: Record<string, BlockConfig> = {
+     // ... existing blocks by type
+     new: NewBlock,
+   }
+   ```
+
+5. **Test Your Block:**  
+   Ensure that the block displays correctly in the UI and that its functionality works as expected.
+
+### How to Create a New Tool
+
+1. **Create a New Directory:**  
+   For tools with multiple related functions, create a directory under `/sim/tools` (e.g., `/sim/tools/newService`).
+
+2. **Create Tool Files:**  
+   Create files for your tool functionality (e.g., `read.ts`, `write.ts`) in your tool directory.
+
+3. **Create an Index File:**  
+   Create an `index.ts` file in your tool directory that imports and exports all tools with appropriate prefixes:
+
+   ```typescript:/sim/tools/newService/index.ts
+   import { readTool } from './read'
+   import { writeTool } from './write'
+
+   export const newServiceReadTool = readTool
+   export const newServiceWriteTool = writeTool
+   ```
+
+4. **Define the Tool Configuration:**  
+   Your tool should export a constant of type `ToolConfig`. For example:
+
+   ```typescript:/sim/tools/newService/read.ts
+   import { ToolConfig, ToolResponse } from '../types'
+
+   interface NewToolParams {
+     apiKey: string
+     query: string
+   }
+
+   interface NewToolResponse extends ToolResponse {
+     output: {
+       result: string
+     }
+   }
+
+   export const readTool: ToolConfig<NewToolParams, NewToolResponse> = {
+     id: 'new_service_read',
+     name: 'New Service Reader',
+     description: 'Description for the new tool',
+     version: '1.0.0',
+
+     // OAuth configuration (if applicable)
+     provider: 'new-service', // ID of the OAuth provider
+     additionalScopes: ['https://api.newservice.com/read'], // Required OAuth scopes
+
+     params: {
+       apiKey: {
+         type: 'string',
+         required: true,
+         description: 'API key for authentication',
+       },
+       query: {
+         type: 'string',
+         required: true,
+         description: 'Query to search for',
+       },
+     },
+     request: {
+       url: 'https://api.example.com/query',
+       method: 'POST',
+       headers: (params) => ({
+         'Content-Type': 'application/json',
+         Authorization: `Bearer ${params.apiKey}`,
+       }),
+       body: (params) => JSON.stringify({ query: params.query }),
+     },
+     transformResponse: async (response: Response) => {
+       const data = await response.json()
+       return {
+         success: true,
+         output: { result: data.result },
+       }
+     },
+     transformError: (error) => {
+       return error.message || 'An error occurred while processing the tool request'
+     },
+   }
+   ```
+
+5. **Register Your Tool:**  
+   Update the tools registry in `/sim/tools/index.ts` to include your new tool. Import from your tool's index.ts file:
+
+   ```typescript:/sim/tools/index.ts
+   import { newServiceReadTool, newServiceWriteTool } from './newService'
+   // ... other imports
+
+   export const tools: Record<string, ToolConfig> = {
+     // ... existing tools
+     new_service_read: newServiceReadTool,
+     new_service_write: newServiceWriteTool,
+   }
+   ```
+
+6. **Test Your Tool:**  
+   Ensure that your tool functions correctly by making test requests and verifying the responses.
+
+### Guidelines & Best Practices
+
+- **Code Style:** Follow the project's ESLint and Prettier configurations. Use meaningful variable names and small, focused functions.
+- **Documentation:** Clearly document the purpose, inputs, outputs, and any special behavior for your block/tool.
+- **Error Handling:** Implement robust error handling and provide user-friendly error messages.
+- **Testing:** Add unit or integration tests to verify your changes when possible.
+- **Commit Changes:** Update all related components and registries, and describe your changes in your pull request.
+
+Happy coding!
+
+---
+
+Thank you for taking the time to contribute to Sim Studio. We truly appreciate your efforts and look forward to collaborating with you!