|
1 | 1 | # Contributing | Firebase Admin Node.js SDK |
2 | 2 |
|
3 | | -## Table of Contents |
| 3 | +This repo contains the Firebase Admin Node.js SDK, which makes it easy for |
| 4 | +developers to write Node.js-based server code that interacts with Firebase |
| 5 | +services. |
4 | 6 |
|
5 | | -1. [Local Setup](#Local-Setup) |
6 | | -2. [Running Tests](#Running-Tests) |
7 | | -3. [Proposing Changes](#Proposing-Changes) |
8 | | -4. [Release Process](#Release-Process) |
9 | | - 1. [Initial Steps](#Initial-Steps) |
10 | | - 2. [Recurring Steps](#Recurring-Steps) |
11 | | -5. [Updating Realtime Database Code](#Updating-Realtime-Database-Code) |
12 | | -6. [Updating Reference Documentation](#Updating-Reference-Documentation) |
13 | | - |
14 | | - |
15 | | -## Local Setup |
16 | | - |
17 | | -Follow the [setup instructions for Git-on-Borg](https://gerrit-internal.git.corp.google.com/docs/+/master/users/from-gmac.md#Setup) |
18 | | -and then clone the repo to your local machine with the commit hook: |
19 | | - |
20 | | -```bash |
21 | | -$ git credential-corpsso login # Similar to prodaccess; need to do this daily |
22 | | -$ git clone sso://team/firebase-team/firebase-admin-node && (cd firebase-admin-node && curl -Lo `git rev-parse --git-dir`/hooks/commit-msg https://gerrit-review.googlesource.com/tools/hooks/commit-msg ; chmod +x `git rev-parse --git-dir`/hooks/commit-msg) |
23 | | -``` |
24 | | - |
25 | | -Next, install all necessary dependencies: |
26 | | - |
27 | | -```bash |
28 | | -$ npm install -g gulp # Install global npm dependencies |
29 | | -$ npm install # Install local npm dependencies |
30 | | -``` |
31 | | - |
32 | | -In order to run the tests, you need to [download the gcloud CLI](https://cloud.google.com/sdk/downloads#interactive) |
33 | | -and run the following command: |
34 | | - |
35 | | -```bash |
36 | | -gcloud beta auth application-default login |
37 | | -``` |
38 | | - |
39 | | -Finally, simply run `gulp` to lint, build, and test the code: |
40 | | - |
41 | | -```bash |
42 | | -$ gulp # Lint, build, and test |
43 | | -``` |
44 | | - |
45 | | - |
46 | | -## Running Tests |
47 | | - |
48 | | -There are two test suites: unit and integration. The unit test suite is intended to be run during |
49 | | -development and the integration test suite is intended to be run before packaging up release |
50 | | -candidates. |
51 | | - |
52 | | -To run the unit test suite: |
53 | | - |
54 | | -```bash |
55 | | -$ gulp # Lint, build, and run unit test suite |
56 | | -``` |
57 | | - |
58 | | -To run the integration test suite: |
59 | | - |
60 | | -```bash |
61 | | -$ node test/integration # Run integration test suite |
62 | | -``` |
63 | | - |
64 | | -The integration test suite requires you to generate a service account key JSON file for the |
65 | | -**admin-sdks-test** Firebase project and save it to `test/resources/key.json`. You can generate this |
66 | | -from the |
67 | | -[**Service Accounts**](https://console.firebase.google.com/project/admin-sdks-test/settings/serviceaccounts/adminsdk) |
68 | | -tab of that project's settings page. |
69 | | - |
70 | | - |
71 | | -## Proposing Changes |
72 | | - |
73 | | -Git-on-Borg requires all reviews to contain just a single commit. To propose a change to this repo, |
74 | | -follow the local setup instructions above. It is important to use the `git clone` command above |
75 | | -which includes the commit hook. Once you are set up locally, create a new feature branch: |
76 | | - |
77 | | -```bash |
78 | | -$ git checkout -b <NEW_BRANCH_NAME> |
79 | | -``` |
80 | | - |
81 | | -After you've made your code changes, commit your files: |
82 | | - |
83 | | -```bash |
84 | | -$ git commit -am "<COMMIT_MESSAGE>" |
85 | | -``` |
86 | | - |
87 | | -To kick off a new CL, upload the changes to Gerrit, the code review tool: |
88 | | - |
89 | | -```bash |
90 | | -$ git push origin HEAD:refs/for/master |
91 | | -``` |
92 | | - |
93 | | -You should see the CL show up [within the Gerrit UI](https://team-review.git.corp.google.com/#/dashboard/self). If you need to make changes after your first commit, you will need to amend the previous |
94 | | -commit so that you only ever have one commit: |
95 | | - |
96 | | -```bash |
97 | | -$ git commit --amend |
98 | | -``` |
99 | | - |
100 | | -You can then upload your changes back to Gerrit via the same `git push` command listed above. |
101 | | - |
102 | | - |
103 | | -## Release Process |
104 | | - |
105 | | -### Initial Steps |
106 | | - |
107 | | -1. Email [email protected] and [email protected] requesting the following: |
108 | | - 1. Read access to the |
109 | | - [`firebase/firebase-client-js`](https://www.github.com/firebase/firebase-client-js) GitHub |
110 | | - repo in order to get the latest Realtime Database code. |
111 | | - 2. Editor access to the |
112 | | - [Firebase Development](https://pantheon.corp.google.com/home/dashboard?project=firebase-dev) |
113 | | - GCP project in order to upload new release tarballs. |
114 | | - 3. Access to the |
115 | | - [Firebase SF production Jenkins instance](https://jenkins-firebase-prod.firebaseint.com/) in |
116 | | - order to do Catapult deploys. |
117 | | - |
118 | | -### Recurring Steps |
119 | | - |
120 | | -1. [If needed] Update `src/database/database.js` to the latest commit. |
121 | | - 1. See [Updating Realtime Database Code](#Updating-Realtime-Database-Code) for details. |
122 | | -2. Prepare release notes for the upcoming release (e.g., |
123 | | - [cl/141203171](https://critique.corp.google.com/#review/141203171)). |
124 | | -3. Create a release tarball containing the code that will be shipped. |
125 | | - 1. Run `$ ./createReleaseTarball.sh X.Y.Z-rc#` where `X.Y.Z` is the SDK's new SemVer version |
126 | | - number and `#` is the release candidate version, starting at `0`. |
127 | | - 2. This will update the `package.json` and `npm-shrinkwrap.json` files as well and create a new |
128 | | - tarball named `firebase-admin-X.Y.Z-rc#.tgz`. |
129 | | -4. Create a CL with the updated `package.json` and `npm-shrinkwrap.json` (e.g., |
130 | | - [gob-cl/56646](https://team-review.git.corp.google.com/#/c/56646/)). |
131 | | -5. Upload the `firebase-admin-X.Y.Z-rc#.tgz` tarball to the |
132 | | - [firebase-admin-node](https://pantheon.corp.google.com/storage/browser/firebase-admin-node/?project=firebase-dev) |
133 | | - GCS bucket within the Firebase Development project. |
134 | | - 1. After uploading, make sure to select "Public link" on the right hand side to ensure the |
135 | | - tarball is publicly accessible. |
136 | | - 2. The tarball can be downloaded via: |
137 | | - `$ npm install https://storage.googleapis.com/firebase-admin-node/firebase-admin-X.Y.Z-rc#.tgz` |
138 | | - 3. When the release is actually going to happen, copy the latest release candidate to |
139 | | - `firebase-admin-X.Y.Z.tgz` (note the lack of a `-rc#` suffix). |
140 | | -6. Deploy the library via [Catapult](https://jenkins-firebase-prod.firebaseint.com/job/catapult/build). |
141 | | - 1. Select "firebase-admin" from the dropdown. |
142 | | - 2. Type the version number into the input box. |
143 | | - 3. Click "Build". |
144 | | -7. Ping someone with OWNERS approval to publish the release notes to production. |
145 | | -8. [If needed] Update the reference documentation if the Admin Node.js externs have changed since |
146 | | - the last release. |
147 | | - 1. See [Updating Reference Documentation](#Updating-Reference-Documentation) for details. |
148 | | -9. Perform some sanity checks. |
149 | | - 1. Make sure that the Jenkins build succeeded. |
150 | | - 1. You can view output from the build by clicking on the build in the "Build History" box on |
151 | | - the left-hand side and then clicking "Console Output". |
152 | | - 2. Ensure that the release was actually published to npm. |
153 | | - 1. `$ npm show firebase-admin version` |
154 | | - 3. Ensure the [@FirebaseRelease](https://twitter.com/firebaserelease) release tweet went out. |
155 | | - |
156 | | - |
157 | | - |
158 | | -## Updating Realtime Database Code |
159 | | - |
160 | | -The code for the Realtime Database in [database/database.js](./database/database.js) of this repo |
161 | | -is imported as a minified file from the [firebase/firebase-client-js](https://github.com/firebase/firebase-client-js) |
162 | | -GitHub repo. To update that code, follow these instructions: |
163 | | - |
164 | | -1. Make sure you have access to the [firebase/firebase-client-js](https://github.com/firebase/firebase-client-js) |
165 | | -GitHub repo. If you do not have access, the above link will 404 and you should send an email to |
166 | | -[email protected] with your GitHub username requesting access. |
167 | | - |
168 | | -2. Clone the GitHub repo. |
169 | | - |
170 | | -3. Configure the repo: |
171 | | - |
172 | | - ``` |
173 | | - $ source tools/use |
174 | | - $ configure-project |
175 | | - ``` |
176 | | - |
177 | | -4. On the `master` branch, compile the Firebase JavaScript client artifacts: |
178 | | - |
179 | | - ``` |
180 | | - $ build-client |
181 | | - ``` |
182 | | - |
183 | | -5. Copy `target/firebase-admin-node.js` of the `firebase/firebase-client-js` repo into |
184 | | -[`src/database/database.js`](./src/database/database.js) of this repo. |
185 | | - |
186 | | -6. Add a comment to the top of the file with the format: |
187 | | - |
188 | | - `/* Copied from firebase/firebase-client-js commit <commit_hash> */` |
189 | | - |
190 | | - where `<commit_hash>` is the commit hash from which you copied the file. |
191 | | - |
192 | | -7. After ensuring all tests still pass, send a CL containing the updated file. |
193 | | - |
194 | | - |
195 | | -# Updating Reference Documentation |
196 | | - |
197 | | -The [reference documentation for this SDK](https://firebase.google.com/docs/reference/admin/node/) |
198 | | -is generated from |
199 | | -[extern files](https://cs.corp.google.com/piper///depot/google3/firebase/jscore/api/admin/) located |
200 | | -in google3. These extern files are the source of truth and should be edited directly. |
201 | | - |
202 | | -To turn these extern files into actual HTML files, run the following from the root `google3/` |
203 | | -directory of a CitC client: |
204 | | - |
205 | | -```bash |
206 | | -$ cd firebase/jscore |
207 | | -$ source tools/use |
208 | | -$ regenerate-admin-reference |
209 | | -``` |
210 | | - |
211 | | -You can then stage the generated HTML files to |
212 | | -[staging Devsite](https://firebase-dot-devsite.googleplex.com/docs/reference/admin/node/): |
213 | | - |
214 | | -```bash |
215 | | -$ devsite stage ../../googledata/devsite/site-firebase/en/docs/reference/admin/node/ |
216 | | -``` |
217 | | - |
218 | | -If things look good on staging Devsite, create a new CL with the updates to the generated files |
219 | | -(e.g., [cl/141195439](https://critique.corp.google.com/#review/141195439)). |
| 7 | +See the [Firebase Admin Node.js SDK |
| 8 | +g3doc](https://g3doc.corp.google.com/firebase/admin_sdks/g3doc/node.md) for |
| 9 | +setup, build, and release instructions. |
0 commit comments