Skip to main content
The Who To Bother web interface makes it easy to contribute without touching Git or command-line tools. This guide walks you through the entire process of submitting a new company or updating existing information.

Prerequisites

Before you begin, make sure you have:

GitHub Account

A GitHub account to authenticate and create pull requests

Company Information

Company details, contact information, and handles ready

SVG Logo

An SVG version of the company logo (preferred format)

Verified Information

Confirmed that all contact information is public and accurate

Adding a New Company

1

Navigate to the contribute page

2

Sign in with GitHub

Click “Sign in with GitHub” and authorize the application
You’ll be asked to grant permissions to access your public repositories. This allows the app to fork the repo and create pull requests on your behalf.
3

Click 'Add New Company'

After signing in, click the “Add New Company” card
4

Fill out the form

Complete all required fields in the contribution form
5

Upload logo

Upload or paste your SVG logo in the logo section
6

Preview your changes

Switch to the Preview tab to see how your company will appear
7

Submit and create PR

Click “Submit & Create PR” to automatically create a pull request

The Contribution Form

Company Information

The form has three tabs for different editing modes:
Visual form interface with fields for all company information

Required Fields

All of these fields must be filled out before you can submit:
Company ID: A unique identifier (lowercase, alphanumeric, dashes only)
  • Example: vercel, github, anthropic
Company Name: The official company name
  • Example: “Vercel”, “GitHub”, “Anthropic”
Description: Brief description of what the company does (1-2 sentences)
  • Example: “Vercel is a cloud platform for static sites and serverless functions”
Logo Type: The key used to reference the logo (usually same as ID)
  • Example: vercel
At least one category: A logical grouping for contacts
  • Example: “Products”, “Engineering”, “Support”
At least one contact: A product/role with at least one valid X handle
  • Example: Product: “Next.js”, Handle: “@leeerob”

Optional Fields

You can also add:
  • Website URL: Company homepage
  • Documentation URL: Link to company docs
  • GitHub URL: Company’s GitHub organization
  • Discord URL: Company’s Discord server
  • Email addresses: Public contact emails (for specific roles)
The logo uploader accepts SVG files. The system will automatically:
  • Add proper width/height attributes (30x30)
  • Add dark mode support via className
  • Replace fill colors with currentColor for theming
  • Validate the SVG structure
Example SVG
<svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
  <title>Company Name</title>
  <circle cx="50" cy="50" r="40" fill="currentColor" />
</svg>

Categories and Contacts

Adding Categories

Categories help organize contacts by product, team, or functional area:
Example Categories
{
  "categories": [
    {
      "name": "Products",
      "contacts": [...]
    },
    {
      "name": "Engineering",
      "contacts": [...]
    },
    {
      "name": "Developer Relations",
      "contacts": [...]
    }
  ]
}

Adding Contacts

Each contact represents a product, role, or topic:
Example Contact
{
  "product": "Next.js",
  "handles": ["@leeerob", "@timneutkens"],
  "email": "[email protected]"
}
Handles must start with @ and contain only letters, numbers, and underscores.

Multiple Handles

You can add multiple X handles for each contact:
Multiple Handles
{
  "product": "API Platform",
  "handles": ["@handle1", "@handle2", "@handle3"]
}

Behind the Scenes: The GitHub Integration

When you click “Submit & Create PR”, the application performs several automated steps:

Step 1: Fork the Repository

src/app/api/github/fork.ts
// Check if fork exists
const existingFork = await getUserFork(accessToken, user.login);

if (!existingFork) {
  // Create new fork
  fork = await forkRepository(accessToken);
  
  // Wait for fork to be ready (GitHub fork creation is async)
  await waitForFork(accessToken, user.login);
}

// Sync fork with upstream to ensure it's up to date
await syncFork(accessToken, user.login);
1

Check for existing fork

The system checks if you’ve already forked the repository
2

Create fork if needed

If no fork exists, creates a new one to your GitHub account
3

Sync with upstream

Ensures your fork is up to date with the main repository

Step 2: Create a Branch

src/app/api/github/create-pr.ts
// Generate unique branch name
const branchName = generateBranchName(
  company.id,
  isEdit,
  user.login
);
// Example: "api-add-vercel-username-1234567890"

// Get the latest commit SHA from main branch
const baseSha = await getBranchSha(
  accessToken,
  workingRepo,
  GITHUB_CONFIG.defaultBranch
);

// Create new branch from main
await createBranch({
  accessToken,
  username: workingRepo,
  branchName,
  sha: baseSha,
});
Branch names follow this pattern:
  • Prefix: api-add (new company) or api-edit (update)
  • Company ID: vercel
  • Username: Your GitHub username
  • Timestamp: Unix timestamp for uniqueness
Result: api-add-vercel-yourname-1708123456

Step 3: Commit Changes

The system commits two files to your branch: 1. Company Data File (src/data/companies/yourcompany.json):
src/app/api/github/create-pr.ts
const companyJson = JSON.stringify(
  {
    $schema: "./schema.json",
    ...company,
  },
  null,
  2
);

await createOrUpdateFile({
  accessToken,
  username: workingRepo,
  path: `src/data/companies/${company.id}.json`,
  content: companyJson,
  message: `feat: add ${company.name} company data`,
  branch: branchName,
});
2. Logo Component (src/components/company-logos.tsx):
src/lib/github.ts
// Get existing logos file
const logosFile = await getFileContent({
  accessToken,
  username: workingRepo,
  path: "src/components/company-logos.tsx",
  branch: branchName,
});

// Inject new logo
const updatedLogosContent = injectLogoIntoTsx(
  logosFile.content,
  company.logoType,
  svgLogo
);

await createOrUpdateFile({
  accessToken,
  username: workingRepo,
  path: "src/components/company-logos.tsx",
  content: updatedLogosContent,
  message: `feat: add ${company.name} logo`,
  branch: branchName,
  existingSha: logosFile.sha,
});

Step 4: Create Pull Request

src/app/api/github/create-pr.ts
const { title, body } = generatePRContent(
  company.id,
  company.name,
  isEdit
);

const pullRequest = await createPullRequest({
  accessToken,
  username: user.login,
  branchName,
  title,
  body,
});

// Returns PR URL: https://github.com/kulterryan/who-to-bother-at-on-x/pull/123
The PR includes:
  • Title: Add: Company Name or Update: Company Name
  • Description: Automatically generated with checklist
  • Branch reference: username:branch-name → kulterryan:main
Example PR body:
## Add Company: Vercel

This PR was automatically generated from the [Who to Bother](https://who-to-bother-at.com) website.

### Changes
- Added company data file: `src/data/companies/vercel.json`
- Added company logo in: `src/components/company-logos.tsx`

### Checklist
- [ ] Company information is accurate
- [ ] Logo displays correctly
- [ ] All contacts have valid X handles

---
*Submitted via the website contribution form*

Visual Progress Indicators

The submission process shows real-time progress:
src/components/contribute/pr-status.tsx
// Status states during submission:
type PRStatusState =
  | { type: "idle" }
  | { type: "forking"; alreadyExists?: boolean }
  | { type: "creating-branch" }
  | { type: "committing" }
  | { type: "creating-pr" }
  | { type: "success"; prUrl: string; prNumber: number }
  | { type: "success-owner"; branch: string }
  | { type: "error"; message: string };
You’ll see messages like:
1

Forking repository...

Creating or verifying your fork of the main repository
2

Creating branch...

Creating a new branch for your changes
3

Committing changes...

Uploading your company data and logo files
4

Creating pull request...

Opening a pull request to the main repository
5

Success!

Your PR is ready for review with a link to view it on GitHub

After Submission

What Happens Next

1

Automatic validation

GitHub Actions runs automated checks:
  • JSON schema validation
  • Valibot schema validation
  • Build process verification
2

Maintainer review

A maintainer will review your contribution for:
  • Accuracy of information
  • Proper logo display
  • Valid X handles
  • Overall quality
3

Feedback or approval

You may receive:
  • Approval and merge
  • Requests for changes
  • Questions about the submission
4

Deployment

Once merged, your changes will be deployed to the live site

Viewing Your Pull Request

After submission, you’ll see a success message with a link to your PR:
Pull request created successfully!
View your PR: https://github.com/kulterryan/who-to-bother-at-on-x/pull/123
Click the link to:
  • View the status of automated checks
  • See maintainer feedback
  • Track the merge status
  • Make additional changes if requested

Making Changes to Your PR

If a maintainer requests changes:
  1. Navigate to your fork on GitHub
  2. Switch to the branch used for the PR
  3. Make the requested changes
  4. Commit and push to the same branch
  5. The PR will automatically update
Alternatively, you can submit a new contribution through the website.

Troubleshooting

”Fork not found” Error

If you see this error:
  1. Wait a few seconds and try again (GitHub fork creation can take time)
  2. Check your GitHub account to verify the fork was created
  3. If the fork exists but error persists, try refreshing the page

”Unauthorized” Error

This means your session has expired:
  1. Sign out and sign back in
  2. Try the submission again
  3. Ensure you granted all required permissions during OAuth

Validation Errors

If the form won’t submit:
Check the validation messages below each field to see what’s missing or incorrect.
Common issues:
  • Company ID: Must be lowercase, alphanumeric, and dashes only
  • Handles: Must start with @ and follow Twitter handle format
  • Email: Must be a valid email format (if provided)
  • SVG Logo: Must be valid SVG XML

Build Failures

If automated checks fail on your PR:
  1. Check the GitHub Actions logs for error details
  2. Common issues include:
    • Invalid JSON syntax
    • Schema validation failures
    • Missing required fields
  3. Make corrections and push updates to your branch

Manual GitHub Workflow

If you prefer to contribute directly via GitHub instead of using the web interface:
# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/who-to-bother-at-on-x.git
cd who-to-bother-at-on-x

# Create a new branch
git checkout -b add-company-name

Best Practices

Following these best practices will help your contribution get merged faster.

Before Submitting

Verify Information: Double-check all handles, emails, and links Test Locally: If possible, clone the repo and test your changes locally Use Preview: Always check the preview tab to see how your company will appear Read Guidelines: Review the contributing guidelines first

During Submission

Accurate Data: Only include verified, public information Quality Logos: Use high-quality SVG logos with proper theming Clear Descriptions: Write concise, informative company descriptions Logical Organization: Group contacts in meaningful categories

After Submission

Monitor Your PR: Check for feedback from maintainers Respond Promptly: Address any requested changes quickly Be Patient: Maintainers review PRs as time allows Stay Engaged: You’ll receive GitHub notifications for PR updates

Example: Complete Submission

Here’s a complete example of adding a company:
{
  "$schema": "./schema.json",
  "id": "acme-corp",
  "name": "Acme Corp",
  "description": "Acme builds cloud infrastructure tools for modern developers",
  "logoType": "acmecorp",
  "website": "https://acme.com",
  "docs": "https://docs.acme.com",
  "github": "https://github.com/acmecorp",
  "categories": [
    {
      "name": "Products",
      "contacts": [
        {
          "product": "Acme Platform",
          "handles": ["@acme_platform"],
          "email": "[email protected]"
        },
        {
          "product": "Acme CLI",
          "handles": ["@acme_cli", "@acme_devtools"]
        }
      ]
    },
    {
      "name": "Support",
      "contacts": [
        {
          "product": "Technical Support",
          "handles": ["@acme_support"],
          "email": "[email protected]"
        }
      ]
    }
  ]
}
This would generate a PR with:
  • Branch: api-add-acme-corp-yourname-1708123456
  • Title: Add: Acme Corp
  • Files: src/data/companies/acme-corp.json and logo in company-logos.tsx

Next Steps

Contributing Guide

Learn more about contribution guidelines and best practices

Authentication

Understand how the GitHub OAuth authentication works

Build docs developers (and LLMs) love