Skip to content

Commit 00ea7ee

Browse files
vkryachkovkryachko
authored
Initial setup for Github Pages (#4427)
1 parent 027ceef commit 00ea7ee

File tree

12 files changed

+500
-0
lines changed

12 files changed

+500
-0
lines changed

‎.github/workflows/jekyll-gh-pages.yml

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
name: Jekyll with GitHub Pages
2+
3+
on:
4+
# Runs on pushes targeting the default branch
5+
push:
6+
branches: ["master"]
7+
paths:
8+
- '.github/workflows/jekyll-gh-pages.yml'
9+
- 'contributor-docs/**'
10+
pull_request:
11+
paths:
12+
- '.github/workflows/jekyll-gh-pages.yml'
13+
- 'contributor-docs/**'
14+
15+
# Allows you to run this workflow manually from the Actions tab
16+
workflow_dispatch:
17+
18+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
19+
permissions:
20+
contents: read
21+
pages: write
22+
id-token: write
23+
24+
# Allow one concurrent deployment
25+
concurrency:
26+
group: "pages"
27+
cancel-in-progress: true
28+
29+
jobs:
30+
build:
31+
runs-on: ubuntu-latest
32+
steps:
33+
- name: Checkout
34+
uses: actions/checkout@v3
35+
- name: Setup Pages
36+
uses: actions/configure-pages@v2
37+
- name: Build with Jekyll
38+
uses: actions/jekyll-build-pages@v1
39+
with:
40+
source: ./contributor-docs
41+
destination: ./_site
42+
- name: Upload artifact
43+
uses: actions/upload-pages-artifact@v1
44+
45+
deploy:
46+
if: ${{ github.event_name == 'push' && github.repository == 'firebase/firebase-android-sdk' }}
47+
environment:
48+
name: github-pages
49+
url: ${{ steps.deployment.outputs.page_url }}
50+
runs-on: ubuntu-latest
51+
needs: build
52+
steps:
53+
- name: Deploy to GitHub Pages
54+
id: deployment
55+
uses: actions/deploy-pages@v1

‎contributor-docs/README.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Contributor documentation
2+
3+
This site is a collection of docs and best practices for contributors to Firebase Android SDKs.
4+
It describes how Firebase works on Android and provides guidance on how to build/maintain a Firebase SDK.
5+
6+
## New to Firebase?
7+
8+
- [Development Environment Setup]({{ site.baseurl }}{% link onboarding/env_setup.md %})
9+
- [Creating a new SDK]({{ site.baseurl }}{% link onboarding/new_sdk.md %})
10+
- [How Firebase works]({{ site.baseurl }}{% link how_firebase_works.md %})

‎contributor-docs/_config.yml

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
title: Contributor documentation
2+
description: Documentation and best practices for Android SDK development
3+
logo: "https://firebase.google.com/downloads/brand-guidelines/SVG/logo-logomark.svg"
4+
5+
remote_theme: just-the-docs/[email protected]
6+
plugins:
7+
- jekyll-remote-theme
8+
9+
color_scheme: dark
10+
11+
# Aux links for the upper right navigation
12+
aux_links:
13+
"SDK Github Repo":
14+
- "//github.com/firebase/firebase-android-sdk"
15+
16+
# Enable or disable the site search
17+
# Supports true (default) or false
18+
search_enabled: true
19+
search:
20+
# Split pages into sections that can be searched individually
21+
# Supports 1 - 6, default: 2
22+
heading_level: 6
23+
# Maximum amount of previews per search result
24+
# Default: 3
25+
previews: 2
26+
# Maximum amount of words to display before a matched word in the preview
27+
# Default: 5
28+
preview_words_before: 3
29+
# Maximum amount of words to display after a matched word in the preview
30+
# Default: 10
31+
preview_words_after: 3
32+
# Set the search token separator
33+
# Default: /[\s\-/]+/
34+
# Example: enable support for hyphenated search words
35+
tokenizer_separator: /[\s/]+/
36+
# Display the relative url in search results
37+
# Supports true (default) or false
38+
rel_url: true
39+
# Enable or disable the search button that appears in the bottom right corner of every page
40+
# Supports true or false (default)
41+
button: false
42+
43+
mermaid:
44+
# Version of mermaid library
45+
# Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/
46+
version: "9.2.2"
47+
# Put any additional configuration, such as setting the theme, in _includes/mermaid_config.js
48+
49+
# Enable or disable heading anchors
50+
heading_anchors: true
51+
52+
# Back to top link
53+
back_to_top: true
54+
back_to_top_text: "Back to top"
55+
56+
# Footer last edited timestamp
57+
last_edit_timestamp: true # show or hide edit time - page must have `last_modified_date` defined in the frontmatter
58+
last_edit_time_format: "%b %e %Y at %I:%M %p" # uses ruby's time format: https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html
59+
60+
61+
# Footer "Edit this page on GitHub" link text
62+
gh_edit_link: true # show or hide edit this page link
63+
gh_edit_link_text: "Edit this page on GitHub"
64+
gh_edit_repository: "https://github.com/firebase/firebase-android-sdk" # the github URL for your repo
65+
gh_edit_branch: "master" # the branch that your docs is served from
66+
gh_edit_source: "contributor-docs" # the source that your files originate from
67+
gh_edit_view_mode: "edit" # "tree" or "edit" if you want the user to jump into the editor immediately

‎contributor-docs/_includes/favicon.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
<link rel="shortcut icon" href="https://firebase.google.com/downloads/brand-guidelines/SVG/logo-logomark.svg" type="image/x-icon">

‎contributor-docs/_includes/nav_footer_custom.html

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
<footer class="site-footer">
2+
&copy; Google LLC {{ 'now' | date: "%Y" }}
3+
</footer>

‎contributor-docs/how_firebase_works.md

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# How Firebase Works
2+
3+
## Background
4+
5+
### Eager Initialization
6+
7+
One of the biggest strengths for Firebase clients is the ease of integration. In a common case, a developer has very few things to do to integrate with Firebase. There is no need to initialize/configure Firebase at runtime. Firebase automatically initializes at application start and begins providing value to developers. A few notable examples:
8+
9+
* `Analytics` automatically tracks app events
10+
* `Firebase Performance` automatically tracks app startup time, all network requests and screen performance
11+
* `Crashlytics` automatically captures all application crashes, ANRs and non-fatals
12+
13+
This feature makes onboarding and adoption very simple. However, comes with the great responsibility of keeping the application snappy. We shouldn't slow down application startup for 3p developers as it can stand in the way of user adoption of their application.
14+
15+
### Automatic Inter-Product Discovery
16+
17+
When present together in an application, Firebase products can detect each other and automatically provide additional functionality to the developer, e.g.:
18+
19+
* `Firestore` automatically detects `Auth` and `AppCheck` to protect read/write access to the database
20+
* `Crashlytics` integrates with `Analytics`, when available, to provide additional insights into the application behavior and enables safe app rollouts
21+
22+
## FirebaseApp at the Core of Firebase
23+
24+
Regardless of what Firebase SDKs are present in the app, the main initialization point of Firebase is `FirebaseApp`. It acts as a container for all SDKs, manages their configuration, initialization and lifecycle.
25+
26+
### Initialization
27+
28+
`FirebaseApp` gets initialized with the help of `FirebaseApp#initializeApp()`. This happens [automatically at app startup](https://firebase.blog/posts/2016/12/how-does-firebase-initialize-on-android) or manually by the developer.
29+
30+
During initialization, `FirebaseApp` discovers all Firebase SDKs present in the app, determines the dependency graph between products(for inter-product functionality) and initializes `eager` products that need to start immediately, e.g. `Crashlytics` and `FirebasePerformance`.
31+
32+
### Firebase Configuration
33+
34+
`FirebaseApp` contains Firebase configuration for all products to use, namely `FirebaseOptions`, which tells Firebase which `Firebase` project to talk to, which real-time database to use, etc.
35+
36+
### Additional Services/Components
37+
38+
In addition to `FirebaseOptions`, `FirebaseApp` registers additional components that product SDKs can request via dependency injection. To name a few:
39+
40+
* `android.content.Context`(Application context)
41+
* [Common Executors](https://github.com/firebase/firebase-android-sdk/blob/master/docs/executors.md)
42+
* `FirebaseOptions`
43+
* Various internal components
44+
45+
## Discovery and Dependency Injection
46+
47+
There are multiple considerations that lead to the current design of how Firebase SDKs initialize.
48+
49+
1. Certain SDKs need to initialize at app startup.
50+
2. SDKs have optional dependencies on other products that get enabled when the developer adds the dependency to their app.
51+
52+
To enable this functionality, Firebase uses a runtime discovery and dependency injection framework [firebase-components](https://github.com/firebase/firebase-android-sdk/tree/master/firebase-components).
53+
54+
To integrate with this framework SDKs register the components they provide via a `ComponentRegistrar` and declare any dependencies they need to initialize, e.g.
55+
56+
```java
57+
public class MyRegistrar implements ComponentRegistrar {
58+
@Override
59+
public List<Component<?>> getComponents() {
60+
return Arrays.asList(
61+
// declare the component
62+
Component.builder(MyComponent.class)
63+
// declare dependencies
64+
.add(Dependency.required(Context.class))
65+
.add(Dependency.required(FirebaseOptions.class))
66+
.add(Dependency.optionalProvider(InternalAuthProvider.class))
67+
// let the runtime know how to create your component.
68+
.factory(
69+
diContainer ->
70+
new MyComponent(
71+
diContainer.get(Context.class),
72+
diContainer.get(FirebaseOptions.class),
73+
diContainer.get(InternalAuthProvider.class)))
74+
.build());
75+
}
76+
}
77+
```
78+
79+
This registrar is then registered in `AndroidManifest.xml` of the SDK and is used by `FirebaseApp` to discover all components and construct the dependency graph.
80+
81+
More details in [Firebase Components]({{ site.baseurl }}{% link in_depth/components.md %})).

‎contributor-docs/in_depth/components.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
parent: In Depth
3+
---
4+
5+
# Firebase Components
6+
7+
TODO

‎contributor-docs/in_depth/in_depth.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
has_children: true
3+
---
4+
5+
# In Depth

‎contributor-docs/onboarding/as_open_project.png

38.9 KB
Loading

‎contributor-docs/onboarding/env_setup.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
parent: Onboarding
3+
---
4+
5+
# Development Environment Setup
6+
7+
This page describes software and configuration required to work on code in the
8+
[Firebase/firebase-android-sdk](https://github.com/firebase/firebase-android-sdk)
9+
repository.
10+
11+
{:toc}
12+
13+
## JDK
14+
15+
The currently required version of the JDK is `11`. Any other versions are
16+
unsupported and using them could result in build failures.
17+
18+
## Android Studio
19+
20+
In general, the most recent version of Android Studio should work. The version
21+
that is tested at the time of this writing is `Dolphin | 2021.3.1`.
22+
23+
Download it here:
24+
[Download Android Studio](https://developer.android.com/studio)
25+
26+
## Emulators
27+
28+
If you plan to run tests on emulators(you should), you should be able to install
29+
them directly from Android Studio's AVD manager.
30+
31+
## Github (Googlers Only)
32+
33+
To onboard and get write access to the github repository you need to have a
34+
github account fully linked with [go/github](http://go/github).
35+
36+
File a bug using this
37+
[bug template](http://b/issues/new?component=312729&template=1016566) and wait
38+
for access to be granted.
39+
40+
After that configure github keys as usual using this
41+
[Github documentation page](https://docs.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh).
42+
43+
## Importing the repository
44+
45+
1. Clone the repository with `git clone --recurse-submodules
46+
[email protected]:firebase/firebase-android-sdk.git`.
47+
1. Open Android Studio and click "Open an existing project".
48+
![Open an existing project](as_open_project.png)
49+
1. Find the `firebase-android-sdk` directory and open.
50+
1. To run integration/device tests you will need a `google-services.json` file.

0 commit comments

Comments
 (0)