# Contributing to XCH Community Dashboard

Thank you for your interest in contributing to the XCH Community Dashboard! This guide will help you add new entities to the dashboard through pull requests.

## How to Add a New Entity

### Step 1: Fork the Repository

1. Click the "Fork" button on the GitHub repository page
2. Clone your forked repository to your local machine:
   ```bash
   git clone https://github.com/your-username/XCH-Community-Dashboard.git
   cd XCH-Community-Dashboard
   ```

### Step 2: Edit the Entities File

1. Open `data/entities.json` in your favorite text editor
2. Add your new entity to the JSON array

### Step 3: Entity Format

Each entity must follow this structure:

```json
{
  "name": "Your Entity Name",
  "description": "A clear, concise description of what your entity is and what it does. This should be 1-2 sentences.",
  "website": "https://your-website.com",
  "sourceCodeUrl": "https://github.com/your-username/your-repo",
  "contributors": ["Your Name", "@yourhandle"],
  "initialReleaseDate": "Month Day, Year",
  "logoImage": "https://your-website.com/logo.png",
  "categories": ["Category1", "Category2"],
  "connections": []
}
```

#### Field Guidelines

- **name** (required): The official name of the entity
- **description** (required): 1-2 sentence description in plain English
- **website** (optional): Full URL including `https://`
- **sourceCodeUrl** (optional): 
  - Use `null` if the source code is not publicly available
  - Otherwise, provide the full URL (GitHub, GitLab, etc.)
- **contributors** (optional): Array of contributor names
  - Use real names, GitHub handles with @, or both
  - Example: `["John Doe", "@johndoe", "Jane Smith"]`
- **initialReleaseDate** (optional): 
  - Format: "Month Day, Year" (e.g., "January 1st, 2023")
  - Use `null` if unknown
- **logoImage** (optional): 
  - URL to the logo image (preferred)
  - Or path to image in `assets/logos/` folder (if you upload it)
  - Image should be square or close to square for best display
  - Recommended size: 100x100px to 200x200px
- **categories** (required): Array of one or more categories
  - Common categories: "News", "Media", "Tools", "Wallets", "Development", "Education", "Community"
  - Use existing categories when possible, or suggest new ones if needed
- **connections** (optional): 
  - Array of entity IDs or names this entity is explicitly connected to
  - Leave as empty array `[]` if no explicit connections
  - Entities with shared categories will be automatically connected

### Step 4: Validating JSON

Before submitting, make sure your JSON is valid:

- All strings must be in double quotes
- No trailing commas
- All brackets and braces must be properly closed
- Use a JSON validator if unsure (e.g., [jsonlint.com](https://jsonlint.com))

### Step 5: Upload Logo (Optional)

If you want to host the logo in the repository:

1. Add your logo image to `assets/logos/`
2. Use a descriptive filename (e.g., `my-entity-logo.png`)
3. Update the `logoImage` field to: `"assets/logos/my-entity-logo.png"`

### Step 6: Commit and Push

1. Stage your changes:
   ```bash
   git add data/entities.json
   git add assets/logos/your-logo.png  # if you added a logo
   ```

2. Commit with a descriptive message:
   ```bash
   git commit -m "Add [Entity Name] to community dashboard"
   ```

3. Push to your fork:
   ```bash
   git push origin main
   ```

### Step 7: Create a Pull Request

1. Go to the original repository on GitHub
2. Click "New Pull Request"
3. Select "compare across forks"
4. Choose your fork and branch
5. Fill out the pull request form:
   - **Title**: "Add [Entity Name]"
   - **Description**: Briefly describe the entity and why it should be included
6. Submit the pull request

## What Happens Next?

1. A maintainer will review your pull request
2. They may ask for changes or clarification
3. Once approved, your entity will be merged and appear on the live dashboard!

## Guidelines

### Entity Eligibility

Entities should be:
- Related to Chia (XCH) blockchain or community
- Actively maintained or historically significant
- Provide value to the Chia community
- Have a clear purpose and description

### Logo Requirements

- Square or near-square aspect ratio
- Clear and recognizable at small sizes
- PNG, SVG, or JPG format
- Recommended: 100x100px to 200x200px
- No offensive or inappropriate content

### Category Suggestions

If your entity doesn't fit existing categories, you can suggest new ones. Common categories include:
- News & Media
- Tools & Utilities
- Wallets
- Development
- Education & Documentation
- Community & Social
- Mining & Farming
- Marketplaces
- DeFi

## Questions?

If you have questions about contributing:
- Open an issue on GitHub
- Check existing issues and pull requests
- Review the README.md for project information

Thank you for contributing to the XCH Community Dashboard! 🎉