Thank you for your interest in contributing and welcome to the Firebase community! 🔥
This guide describes the many ways to contribute to Firebase and outlines the preferred workflow for Firebase development.
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.
Check out issues marked as:
Additionally, have a look at the Roadmap to see Firebase's longer term goals. There are many opportunities to get involved!
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!
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.
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.
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:
brew install clang-format@17 brew install mint
Next, clone the Firebase repo.
-
Clone via HTTPS
git clone https://github.com/firebase/firebase-ios-sdk.git -
Or via SSH
git clone [email protected]:firebase/firebase-ios-sdk.git
Once the necessary tools have been installed and the project has been cloned, continue on to the preferred development workflow.
The workflow for library development is different from application development. For Firebase development, we develop using the same tools we use to distribute Firebase. Instructions for developing with Swift Package Manager and CocoaPods are as follows:
Swift Package Manager is built into Xcode and makes it simple to develop projects with multiple dependencies.
To develop using SwiftPM, open the Package.swift file in your cloned
Firebase copy (or open Package.swift from the command line) and select a
library scheme to build and develop that library.
To learn more about running tests with Swift Package Manager, visit the Testing section.
CocoaPods is another popular dependency manager used in Apple development.
Firebase supports development with CocoaPods 1.10.0 (or later). If you choose to
develop using CocoaPods, it's recommend to use
cocoapods-generate, a plugin that generates a
workspace from a podspec. This plugin allows you to quickly generate a
development workspace using any library's podspec. All of the podspecs for
Firebase's libraries are located in the repo's root directory.
-
To check if your machine has CocoaPods installed, run
pod --versionin terminal. If the command fails with acommand not founderror, then you'll need to install CocoaPods.To install, please refer to CocoaPods's Getting Started guide.
-
Please see cocoapods-generate for instructions on how to install.
With CocoaPods and cocoapods-generate installed, the pod gen command
makes it easy to develop specific Firebase libraries.
pod gen Firebase{name here}.podspec --local-sources=./ --auto-open --platforms=ios- If the CocoaPods cache is out of date, you may need to run
pod repo updatebefore thepod gencommand. - Set the
--platformsoption tomacosortvosto develop on those platforms. Since 10.2, Xcode does not properly handle multi-platform CocoaPods workspaces.
Developing for Mac Catalyst?
To develop for Mac Catalyst, there are a few additional steps to configure the project.
- Run
pod gen {name here}.podspec --local-sources=./ --auto-open --platforms=ios - Check the Mac box in the host app's Build Settings
- Sign the host app in the Signing & Capabilities tab
- Navigate to Pods in the Project Manager
- Add Signing to the host app and unit test targets
- Select the Unit-unit scheme
- Run it to build and test
Alternatively, disable signing in each target:
- Go to Build Settings tab
- Click +
- Select Add User-Defined Setting
- Add
CODE_SIGNING_REQUIREDsetting with a value ofNO
This code in this repo is styled in accordance to swiftformat and
clang-format conventions.
The ./scripts/style.sh script makes it easy to style your code during development. Running the style script on the folder you worked in is the most efficient way to only format your changes changes.
For example, if your changes were done in FirebaseStorage/Sources/:
./scripts/style.sh FirebaseStorage/Sources/Alternatively, the script can be work on branch names or filenames.
./scripts/style.sh fix-storage-bug./scripts/style.sh FirebaseStorage/Sources/Storage.swiftMore details on using the style.sh script
# Usage:
# ./scripts/style.sh [branch-name | filenames]
#
# With no arguments, formats all eligible files in the repo
# Pass a branch name to format all eligible files changed since that branch
# Pass a specific file or directory name to format just files found there
#
# Commonly
# ./scripts/style.sh your_branchIf 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.
Refer to the following resources when writing Swift or Objective-C code.
- Swift
- Objective-C
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.
View the workflow
For developers without write access, you'll need to create a fork of Firebase instead of a branch. Learn more about forking a repo here.
# Update your local master
git checkout master
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. 🎉Xcode ships with many debugging tools. Learn more about debugging in Xcode by watching WWDC sessions about debugging and viewing the documentation.
Tests are an essential part to building Firebase. Many of the tests for Firebase run as part of our continous 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?
- To enable schemes for testing: run
./scripts/setup_spm_tests.sh - Then in Xcode, choose a scheme to build a library or run a test suite.
- 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.
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.
Before opening a pull request (PR), ensure that your contribution meets the following criteria:
- A descriptive PR description has been written that explains the purpose of this contribution.
- The committed code has been styled in accordance with this repo's style guidelines.
- A CHANGELOG has been updated to reflect the PR's associated changes.
- Unit and/or integration tests have been added or updatd to test and validate the contribution's changes.
- 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.