Skip to main content

​
Overview

X welcomes contributions from the community to improve the recommendation algorithm. This guide outlines how to contribute effectively, from submitting issues to creating pull requests.
X is working on tools to manage community suggestions and sync changes to their internal repository. Contributions help improve the algorithm through collective intelligence and expertise.

​
Ways to Contribute

There are several ways you can contribute to the X Recommendation Algorithm:
  1. Report bugs - Help identify issues in the code
  2. Suggest improvements - Propose enhancements to the algorithm
  3. Submit code changes - Fix bugs or implement new features
  4. Improve documentation - Help others understand the system
  5. Report security vulnerabilities - Keep the platform secure

​
Before You Start

1

Read the Documentation

Familiarize yourself with:
2

Set Up Your Development Environment

Follow the development setup guide to configure your environment and understand the codebase structure.
3

Understand the Build System

Review the building and testing guide to learn how to build and test your changes using Bazel.

​
Reporting Issues

The community is invited to submit GitHub issues for suggestions on improving the recommendation algorithm.

​
Creating an Issue

1

Search Existing Issues

Before creating a new issue, search the existing issues to avoid duplicates.
2

Choose the Right Issue Type

Select the appropriate issue type:
  • Bug Report - Something isn’t working as expected
  • Feature Request - Suggest a new feature or improvement
  • Question - Ask for clarification about the algorithm
  • Documentation - Improvements to docs or examples
3

Provide Detailed Information

Include:
  • Clear title - Summarize the issue in one line
  • Description - Explain the issue or suggestion in detail
  • Steps to reproduce - For bugs, provide reproduction steps
  • Expected behavior - What should happen
  • Actual behavior - What actually happens
  • Environment - OS, Bazel version, Java version, etc.
  • Code snippets - Relevant code or build targets

​
Issue Example

**Title:** Home Mixer fails to build with Bazel 6.0

**Description:**
When attempting to build the home-mixer component using Bazel 6.0,
the build fails with a dependency resolution error.

**Steps to Reproduce:**
1. Install Bazel 6.0
2. Run `bazel build //home-mixer:bin`
3. Observe the error

**Expected Behavior:**
Build should complete successfully

**Actual Behavior:**
Build fails with error: [error message]

**Environment:**
- OS: Ubuntu 22.04
- Bazel: 6.0.0
- Java: OpenJDK 11.0.16

​
Submitting Pull Requests

The community is invited to submit pull requests with code improvements.

​
Pull Request Process

1

Fork the Repository

Create a fork of the repository to your GitHub account:
# Fork on GitHub UI, then clone your fork
git clone https://github.com/YOUR_USERNAME/the-algorithm.git
cd the-algorithm
2

Create a Feature Branch

Create a branch for your changes:
git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix
3

Make Your Changes

  • Write clean, well-documented code
  • Follow existing code style and conventions
  • Add tests for new functionality
  • Ensure all tests pass
4

Test Your Changes

Build and test the affected components:
# Build your changes
bazel build //path/to/your/component:target

# Run tests
bazel test //path/to/your/component/...
5

Commit Your Changes

Write clear, descriptive commit messages:
git add .
git commit -m "Fix: Description of what you fixed"
# or
git commit -m "Feature: Description of what you added"
6

Push to Your Fork

git push origin feature/your-feature-name
7

Create a Pull Request

  1. Go to the original repository on GitHub
  2. Click “New Pull Request”
  3. Select your fork and branch
  4. Fill out the PR template with:
    • Clear description of changes
    • Related issue numbers
    • Testing performed
    • Any breaking changes

​
Pull Request Guidelines

Code Quality

  • Follow Scala/Java/Python style guides
  • Write clear, self-documenting code
  • Add comments for complex logic
  • Keep functions focused and small

Testing

  • Add unit tests for new code
  • Ensure all existing tests pass
  • Test edge cases and error conditions
  • Include integration tests where applicable

Documentation

  • Update relevant README files
  • Add code comments and docstrings
  • Document configuration changes
  • Update API documentation if needed

Commits

  • Write descriptive commit messages
  • Keep commits focused and atomic
  • Reference related issues
  • Squash commits if requested

​
Code Style Guidelines

​
Scala

// Use descriptive names
val userInteractionScore: Double = calculateScore(user, tweet)

// Prefer immutability
val scores = candidates.map(c => scoreCandidate(c))

// Use pattern matching
result match {
  case Success(value) => processValue(value)
  case Failure(error) => handleError(error)
}

// Add type annotations for public methods
def rankCandidates(candidates: Seq[Candidate]): Seq[RankedCandidate] = {
  // implementation
}

​
Java

// Use descriptive names and proper formatting
public class TweetCandidate {
    private final long tweetId;
    private final double score;
    
    public TweetCandidate(long tweetId, double score) {
        this.tweetId = tweetId;
        this.score = score;
    }
    
    // Getters, equals, hashCode, toString
}

​
Python

# Follow PEP 8
import numpy as np
from typing import List, Dict

def calculate_engagement_score(
    features: Dict[str, float],
    weights: np.ndarray
) -> float:
    """
    Calculate engagement score from features and weights.
    
    Args:
        features: Feature dictionary
        weights: Model weights
        
    Returns:
        Engagement probability score
    """
    # implementation
    pass

​
Security Vulnerabilities

Do NOT report security vulnerabilities through GitHub issues.
Any security concerns or issues should be routed to X’s official bug bounty program through HackerOne.
1

Assess the Vulnerability

Determine if the issue is a genuine security vulnerability that could impact user privacy, data integrity, or platform security.
2

Submit to HackerOne

Report the vulnerability through X’s official bug bounty program:https://hackerone.com/x
3

Do Not Disclose Publicly

Do not publicly disclose the vulnerability until X has had time to address it and coordinate a disclosure timeline.

​
What Qualifies as a Security Issue?

  • Privacy violations or data exposure
  • Authentication or authorization bypasses
  • Injection vulnerabilities (SQL, code, etc.)
  • Algorithmic manipulation that could enable abuse
  • Credential leaks or secrets in code
  • Denial of service vulnerabilities

​
Review Process

After submitting a pull request:
  1. Automated checks - CI/CD pipelines will run tests and linters
  2. Code review - X engineers will review your code
  3. Feedback - You may be asked to make changes
  4. Approval - Once approved, your PR will be merged
  5. Internal sync - X will sync changes to their internal repository
X is developing tools to manage community contributions and sync them with their internal codebase. The review process may evolve as these tools are implemented.

​
Communication

​
GitHub Discussions

Use GitHub Discussions for:
  • General questions about the algorithm
  • Design discussions for major features
  • Community collaboration and ideation

​
Issue Comments

Use issue comments for:
  • Discussing specific bugs or features
  • Providing additional context
  • Coordinating with other contributors

​
Pull Request Comments

Use PR comments for:
  • Responding to code review feedback
  • Explaining implementation decisions
  • Discussing technical trade-offs

​
Recognition

Contributors who help improve the algorithm will be recognized through:
  • GitHub contribution history
  • Acknowledgment in release notes (for significant contributions)
  • Community appreciation
X hopes to benefit from the collective intelligence and expertise of the global community in helping identify issues and suggest improvements, ultimately leading to a better X.

​
Additional Resources

Engineering Blog

Technical deep-dive into how the algorithm works

Open Source Initiative

Learn about X’s commitment to transparency

Bug Bounty Program

Report security vulnerabilities responsibly

GitHub Repository

Browse the source code and issues

​
Questions?

If you have questions about contributing:
  1. Check existing issues and discussions
  2. Review the repository documentation
  3. Ask in GitHub Discussions
  4. Create an issue if your question reveals a documentation gap
Thank you for helping improve the X Recommendation Algorithm!

Build docs developers (and LLMs) love

Get started for freeTalk to us