CONTRIBUTING.md

Contributing to Firebase

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.

Contents

• 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

---

Reporting a bug

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.

Making a feature request

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.

Starting a discussion

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.

Contributing code

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.

---

Development Guide

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 & mint

  Firebase use's a style script that requires clang-format and mint.

  To install clang-format and mint using Homebrew:

  brew install clang-format@13
  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.

Developing

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

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

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.

Installation

• CocoaPods

  To check if your machine has CocoaPods installed, run pod --version in terminal. If the command fails with a command not found error, then you'll need to install CocoaPods.

  To install, please refer to CocoaPods's Getting Started guide.

• cocoapods-generate

  Please see cocoapods-generate for instructions on how to install.

Developing with CocoaPods

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 update before the pod gen command.
• Set the --platforms option to macos or tvos to 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.

1. Run pod gen {name here}.podspec --local-sources=./ --auto-open --platforms=ios
2. Check the Mac box in the host app's Build Settings
3. Sign the host app in the Signing & Capabilities tab
4. Navigate to Pods in the Project Manager
5. Add Signing to the host app and unit test targets
6. Select the Unit-unit scheme
7. Run it to build and test

Alternatively, disable signing in each target:

1. Go to Build Settings tab
2. Click +
3. Select Add User-Defined Setting
4. Add CODE_SIGNING_REQUIRED setting with a value of NO

Style Guide

This code in this repo is styled in accordance to clang-format conventions.

Styling your code

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/FIRStorage.m

More 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_branch

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.

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. 🎉

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 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?

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.

---

Contributor License Agreement

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.

Code of Conduct

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.

License

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