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
Navigate to the contribute page
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.
The Contribution Form
Company Information
The form has three tabs for different editing modes:- Form
- Preview
- Code Editor
Visual form interface with fields for all company information
Required Fields
Company ID: A unique identifier (lowercase, alphanumeric, dashes only)- Example:
vercel,github,anthropic
- Example: “Vercel”, “GitHub”, “Anthropic”
- Example: “Vercel is a cloud platform for static sites and serverless functions”
- Example:
vercel
- Example: “Products”, “Engineering”, “Support”
- 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)
SVG Logo
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
currentColorfor theming - Validate the SVG structure
Example SVG
Categories and Contacts
Adding Categories
Categories help organize contacts by product, team, or functional area:Example Categories
Adding Contacts
Each contact represents a product, role, or topic:Example Contact
Handles must start with
@ and contain only letters, numbers, and underscores.Multiple Handles
You can add multiple X handles for each contact:Multiple Handles
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
Step 2: Create a Branch
src/app/api/github/create-pr.ts
- Prefix:
api-add(new company) orapi-edit(update) - Company ID:
vercel - Username: Your GitHub username
- Timestamp: Unix timestamp for uniqueness
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
src/components/company-logos.tsx):
src/lib/github.ts
Step 4: Create Pull Request
src/app/api/github/create-pr.ts
- Title:
Add: Company NameorUpdate: Company Name - Description: Automatically generated with checklist
- Branch reference:
username:branch-name → kulterryan:main
Visual Progress Indicators
The submission process shows real-time progress:src/components/contribute/pr-status.tsx
After Submission
What Happens Next
Automatic validation
GitHub Actions runs automated checks:
- JSON schema validation
- Valibot schema validation
- Build process verification
Maintainer review
A maintainer will review your contribution for:
- Accuracy of information
- Proper logo display
- Valid X handles
- Overall quality
Feedback or approval
You may receive:
- Approval and merge
- Requests for changes
- Questions about the submission
Viewing Your Pull Request
After submission, you’ll see a success message with a link to your PR:- 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:- Navigate to your fork on GitHub
- Switch to the branch used for the PR
- Make the requested changes
- Commit and push to the same branch
- The PR will automatically update
Troubleshooting
”Fork not found” Error
If you see this error:- Wait a few seconds and try again (GitHub fork creation can take time)
- Check your GitHub account to verify the fork was created
- If the fork exists but error persists, try refreshing the page
”Unauthorized” Error
This means your session has expired:- Sign out and sign back in
- Try the submission again
- Ensure you granted all required permissions during OAuth
Validation Errors
If the form won’t submit: 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:- Check the GitHub Actions logs for error details
- Common issues include:
- Invalid JSON syntax
- Schema validation failures
- Missing required fields
- 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:Best Practices
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 firstDuring 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 categoriesAfter 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 updatesExample: Complete Submission
Here’s a complete example of adding a company:- Branch:
api-add-acme-corp-yourname-1708123456 - Title:
Add: Acme Corp - Files:
src/data/companies/acme-corp.jsonand logo incompany-logos.tsx
Next Steps
Contributing Guide
Learn more about contribution guidelines and best practices
Authentication
Understand how the GitHub OAuth authentication works