Contributing to Firebase

• Reporting a bug
• Making a feature request
• Starting a discussion

• Contributing code

• Development Guide

  • Getting started
  • Developing
  • Debugging
  • Testing
  • Opening a pull request

• Contributor License Agreement

• Code of Conduct
• License

To report a bug, fill out a new issue here. The pre-populated form should be filled out accordingly to provide others with useful information regarding the discovered bug. In most cases, a minimal reproducible example is very helpful in allowing us to quickly reproduce the bug and work on a fix.

Feature requests should ideally be clear and concise (i.e. Add Sign in with Apple support). If the feature request is more specific, describe it by providing a use case that is not achievable with existing Firebase APIs and include an API proposal that would make the use case possible. The proposed API change does not need to be very detailed.

To make a feature request, fill out a new feature request form here.

For large or ambiguous requests, such as significant breaking changes or use cases that require multiple new features, consider instead starting a Pitch to discuss and flush out ideas with the Firebase community.

We are using GitHub discussions as a collaborative space where developers can discuss questions and proposals regarding Firebase. For large proposals, start a Pitch to discuss ideas with the community.

View the Firebase discussions or start one here.

Before starting work on a contribution, it's important to allow the Firebase community an opportunity to discuss your proposal. First, check to see if your proposal has appeared in an existing issue's discussion. If it has not, create a new issue and use it to describe and explain your idea. The Firebase team is happy to provide feedback and advice for how to best implement your proposal.

Need some inspiration?

Check out issues marked as:

• help wanted
• type: feature request

Additionally, have a look at the Roadmap to see Firebase's longer term goals. There are many opportunities to get involved!

API Review

Please note that changes or additions to public APIs require an internal API review from the Firebase team. Contributions involving such changes will require additional time to allow for an internal API review to be scheduled and thoroughly conducted. We appreciate your patience while we review your amazing contributions!

Breaking Changes

Firebase's release schedule is designed to reduce the amount of breaking changes that developers have to deal with. Ideally, breaking changes should be avoided when making a contribution.

Using GitHub pull requests

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Refer to GitHub Help for more information on using pull requests. If you're ready to open a pull request, check that you have completed all of the steps outlined in the Opening a pull request section.

The majority of the remaining portion of this guide is dedicated to detailing the preferred workflow for Firebase development.

Getting started

To develop Firebase software, install:

• Xcode (v12.2 or later) (for Googlers, visit go/xcode) to download.
• Code styling tools: clang-format, swiftformat and mint

  Firebase use's a style script that requires clang-format and mint. mint installs [swiftformat] for Swift styling. To install clang-format and mint using Homebrew: console brew install clang-format@18 brew install mint

If your PR is failing CI due to style issues please use the style script accordingly. If the style script is not working, ensure you have installed the necessary code styling tools outlined in the Getting Started section.

Apple development style guides and resources

Refer to the following resources when writing Swift or Objective-C code.

• Swift
  • Google's Swift Style Guide
  • Swift's API Design Guidelines
• Objective-C
  • Google's Objective-C Style Guide
  • Apple's Coding Guidelines for Cocoa

An example Git workflow

This is a general overview of what the Git workflow may look like, from start to finish, when contributing code to Firebase. The below snippet is purely for reference purposes and is used to demonstarate what the workflow may look like, from start to finish.

# Update your local main
git checkout main
git pull

# Create a development branch
git checkout -b my_feature_or_bug_fix

# Code, commit, repeat
git commit -m "a helpful commit message"

# Push your local branch to the remote
git push --set-upstream origin my_feature_or_bug_fix

# Open a pull request on github.com

# Resolve review feedback on opened PR
git commit -m "implemented suggestion"
git push

# Once your PR has been reviewed and all feedback addressed, it
# will be approved and merged by a project member. 🎉

Debugging

Xcode ships with many debugging tools. Learn more about debugging in Xcode by watching WWDC sessions about debugging and viewing the documentation.

Testing

Tests are an essential part to building Firebase. Many of the tests for Firebase run as part of our continuous integration (CI) setup with GitHub Actions.

• Fixing a bug? Add a test to catch potential regressions in the future.
• Adding a new feature? Add tests to test the new or modified APIs. In addition, highlight the new API by providing snippets of how it is used in the API's corresponding issue or PR. These snippets will be linked to the release notes so other developers can see how the API is used. If more context is required to demonstrate the API, reach out to a project member about creating an example project to do so.

Oftentimes, tests can be useful in understanding how a particular API works. Keep this in mind while adding tests as they can serve as an additional tool for demonstrating how an API should be used.

Using Swift Package Manager?

1. To enable schemes for testing: run ./scripts/setup_spm_tests.sh
2. Then in Xcode, choose a scheme to build a library or run a test suite.
3. Choose a target platform by selecting the run destination along with the scheme.

At this time, not all test schemes are configured to run when using Swift Package Manager.

Once a development workspace has been set up and a testing scheme selected, tests can be run by clicking the "play" arrow in the project navigation bar or by using the ⌘U keyboard shortcut.

Viewing Code Coverage

When creating tests, it's helpful to verify that certain codepaths are indeed getting tested. Xcode has a built-in code coverage tool that makes it easy to know what codepaths are run. To enable it, navigate from Product → Scheme ➞ Edit Scheme or use the ⌥⌘U keyboard shortcut to show the current testing scheme. Enable code coverage by selecting the Options tab and checking the Code Coverage box.

The Firebase repo contains a code coverage report tool. To learn more, view the code coverage report documentation.

Opening a pull request

Before opening a pull request (PR), ensure that your contribution meets the following criteria:

1. A descriptive PR description has been written that explains the purpose of this contribution.
2. The committed code has been styled in accordance with this repo's style guidelines.
3. A CHANGELOG has been updated to reflect the PR's associated changes.
4. Unit and/or integration tests have been added or updatd to test and validate the contribution's changes.
5. Refer to the Contributor License Agreement section below to sign a CLA.

Contributions to this project must be accompanied by a Contributor License Agreement (CLA). You (or your employer) retain the copyright to your contribution, this simply gives us permission to use and redistribute your contributions as part of the project. Head over to the Google CLA dashboard to sign a new one or to see your current agreements on file.

You generally only need to submit a CLA once, so if you've already submitted one (even if it was for a different project), you probably don't need to do it again.

We aim to foster a community of learning and kindness at Firebase. By participating, you are expected to have reviewed and agreed to our Code of Conduct.

For more information about the license used for this project, please refer to LICENSE.