tubestation/CONTRIBUTING.md

Contributing to Waterfox

Thank you for your interest in contributing to Waterfox! This guide will help you understand our contribution process and how to effectively work with our codebase.

Table of Contents

• Code of Conduct
• Getting Started
• Pull Request Process
• Managing Upstream Changes
• Contribution Guidelines
• Reporting Bugs
• Suggesting Features

Code of Conduct

Don't be an ass. We are all human.

Getting Started

Before contributing, please:

1. Fork the repository
2. Set up your development environment following our Build Guide
3. Create a new branch for your changes
4. Make your changes
5. Test thoroughly

Pull Request Process

We welcome pull requests but have a few important considerations:

1. Limited Review Bandwidth: The core team has limited availability to review PRs. While we appreciate your contributions, please understand that it may take time for your PR to be reviewed and merged.

2. Not All PRs Will Be Accepted: We maintain specific technical and design directions for Waterfox. Even well-implemented features might not be accepted if they don't align with this direction. Please don't be discouraged if your PR is declined.

3. PR Requirements:

   • Ensure your code follows our coding style
   • Include tests where appropriate
   • Update documentation to reflect any changes
   • Keep PRs focused on a single issue/feature
   • Provide a clear description explaining the purpose and implementation details

4. Review Process:

   • PRs require approval from at least one maintainer
   • You may be asked to make changes before your PR is accepted
   • Please respond to review comments in a timely manner

Managing Upstream Changes

Waterfox is based on Firefox, and we maintain our changes as commits on top of the upstream codebase. This creates some complexity when working with the repository:

How Our Update Process Works

1. We regularly pull in upstream changes from Firefox
2. We rebase our Waterfox-specific changes on top of these updates
3. This rebasing changes the commit hashes of our modifications
4. As a result, simple git pull operations can lead to significant merge conflicts

Keeping Your Fork in Sync

If you're working on a contribution, follow these steps to avoid headaches:

Before Starting New Work

# Ensure you have the Waterfox repo as a remote
git remote add upstream https://github.com/BrowserWorks/Waterfox.git

# Fetch the latest changes
git fetch upstream

# Reset your main branch to match upstream
git checkout main
git reset --hard upstream/main

# Create a new branch for your work
git checkout -b my-feature-branch

During Active Development (When Upstream Changes)

If you're in the middle of development and the upstream Waterfox repository has changed:

# Stash any uncommitted changes
git stash

# Update your main branch
git checkout main
git fetch upstream
git reset --hard upstream/main

# Rebase your feature branch
git checkout my-feature-branch
git rebase main

# Resolve any conflicts that arise during rebase
# After resolving each file:
git add <resolved-file>
git rebase --continue

# Restore your stashed changes if needed
git stash pop

Alternative: Branch from Main and Cherry-Pick

Sometimes a full rebase is too complex. In that case:

# Create a new branch from updated main
git checkout main
git pull upstream main
git checkout -b my-feature-branch-new

# Cherry-pick your commits from the old branch
git cherry-pick <commit-hash>
# Resolve conflicts as needed

# Once all commits are transferred, you can continue work on the new branch

Identifying Your Changes After Upstream Updates

After a major upstream update, finding your specific changes can be challenging. These approaches may help:

1. Use commit messages: Maintain descriptive commit messages that clearly identify Waterfox-specific changes
2. Create feature branches: Keep work isolated in feature branches before submitting PRs
3. Use git blame with caution: The rebasing process changes commit hashes, so git blame might not show the original author

Contribution Guidelines

Code Style

• Follow the existing code style in the files you're modifying
• For JavaScript/C++, we generally follow Mozilla's coding style
• Use meaningful variable names and add comments for complex logic

Commit Messages

• Use clear, descriptive commit messages
• Start with a conventional commit type prefix:
  • fix: for bug fixes
  • feat: for new features
  • docs: for documentation changes
  • style: for formatting, missing semi-colons, etc.
  • refactor: for code changes that neither fix bugs nor add features
  • perf: for performance improvements
  • test: for adding or correcting tests
  • chore: for routine tasks, dependency updates, etc.
  • ci: for CI/CD related changes
• After the prefix, provide a brief summary (50 chars or less)
• If needed, provide a more detailed explanation after a blank line
• Important: Do not reference issue numbers in commit messages to avoid notification spam during rebases

Documentation

• Update documentation to reflect your changes
• Add comments to explain non-obvious code sections
• If adding new features, update relevant README or documentation files

Reporting Bugs

When reporting bugs:

1. Use the GitHub Issues tracker
2. Check if the issue already exists before creating a new one
3. Include detailed steps to reproduce
4. Provide system information (OS, Waterfox version, etc.)
5. Include screenshots or videos if applicable

Suggesting Features

We welcome feature suggestions:

1. First, check if the feature has already been suggested
2. Provide a clear description of the feature and its benefits
3. Understand that not all features will be implemented, based on our priorities and resources

Thank you for contributing to Waterfox!