|
| 1 | +# Contributing | Firebase Admin Node.js SDK |
| 2 | + |
| 3 | +Thank you for contributing to the Firebase community! |
| 4 | + |
| 5 | + - [Have a usage question?](#question) |
| 6 | + - [Think you found a bug?](#issue) |
| 7 | + - [Have a feature request?](#feature) |
| 8 | + - [Want to submit a pull request?](#submit) |
| 9 | + - [Need to get set up locally?](#local-setup) |
| 10 | + |
| 11 | + |
| 12 | +## <a name="question"></a>Have a usage question? |
| 13 | + |
| 14 | +We get lots of those and we love helping you, but GitHub is not the best place for them. Issues |
| 15 | +which just ask about usage will be closed. Here are some resources to get help: |
| 16 | + |
| 17 | +- Go through the [guides](https://firebase.google.com/docs/admin/setup/) |
| 18 | +- Read the full [API reference](https://firebase.google.com/docs/reference/admin/node/) |
| 19 | + |
| 20 | +If the official documentation doesn't help, try asking a question on the |
| 21 | +[Firebase Google Group](https://groups.google.com/forum/#!forum/firebase-talk/) or one of our |
| 22 | +other [official support channels](https://firebase.google.com/support/). |
| 23 | + |
| 24 | +**Please avoid double posting across multiple channels!** |
| 25 | + |
| 26 | + |
| 27 | +## <a name="issue"></a>Think you found a bug? |
| 28 | + |
| 29 | +Yeah, we're definitely not perfect! |
| 30 | + |
| 31 | +Search through [old issues](https://github.com/firebase/firebase-admin-node/issues) before |
| 32 | +submitting a new issue as your question may have already been answered. |
| 33 | + |
| 34 | +If your issue appears to be a bug, and hasn't been reported, |
| 35 | +[open a new issue](https://github.com/firebase/firebase-admin-node/issues/new). Please use the |
| 36 | +provided bug report template and include a minimal repro. |
| 37 | + |
| 38 | +If you are up to the challenge, [submit a pull request](#submit) with a fix! |
| 39 | + |
| 40 | + |
| 41 | +## <a name="feature"></a>Have a feature request? |
| 42 | + |
| 43 | +Great, we love hearing how we can improve our products! Share you idea through our |
| 44 | +[feature request support channel](https://firebase.google.com/support/contact/bugs-features/). |
| 45 | + |
| 46 | + |
| 47 | +## <a name="submit"></a>Want to submit a pull request? |
| 48 | + |
| 49 | +Sweet, we'd love to accept your contribution! |
| 50 | +[Open a new pull request](https://github.com/firebase/firebase-admin-node/pull/new/master) and fill |
| 51 | +out the provided template. |
| 52 | + |
| 53 | +**If you want to implement a new feature, please open an issue with a proposal first so that we can |
| 54 | +figure out if the feature makes sense and how it will work.** |
| 55 | + |
| 56 | +Make sure your changes pass our linter and the tests all pass on your local machine. We've hooked |
| 57 | +up this repo with continuous integration to double check those things for you. |
| 58 | + |
| 59 | +Most non-trivial changes should include some extra test coverage. If you aren't sure how to add |
| 60 | +tests, feel free to submit regardless and ask us for some advice. |
| 61 | + |
| 62 | +Finally, you will need to sign our |
| 63 | +[Contributor License Agreement](https://cla.developers.google.com/about/google-individual) |
| 64 | +before we can accept your pull request. |
| 65 | + |
| 66 | + |
| 67 | +## <a name="local-setup"></a>Need to get set up locally? |
| 68 | + |
| 69 | + |
| 70 | +### Initial Setup |
| 71 | + |
| 72 | +Run the following commands from the command line to get your local environment set up: |
| 73 | + |
| 74 | +```bash |
| 75 | +$ git clone https://github.com/firebase/firebase-admin-node.git |
| 76 | +$ cd firebase-admin-node # go to the firebase-admin-node directory |
| 77 | +$ npm install -g gulp # globally install gulp task runner |
| 78 | +$ npm install # install local npm build / test dependencies |
| 79 | +``` |
| 80 | + |
| 81 | +In order to run the tests, you also need to |
| 82 | +[download the `gcloud` CLI](https://cloud.google.com/sdk/downloads), run the following command, and |
| 83 | +follow the prompts: |
| 84 | + |
| 85 | +```bash |
| 86 | +$ gcloud beta auth application-default login |
| 87 | +``` |
| 88 | + |
| 89 | +### Lint, Build, and Test |
| 90 | + |
| 91 | +Source files are written in [TypeScript](https://www.typescriptlang.org/) and linted using |
| 92 | +[TSLint](https://palantir.github.io/tslint/). Tests are run on the compiled JavaScript files. |
| 93 | + |
| 94 | +The lint, build, and test process is kicked off via the default `gulp` task, although you can also |
| 95 | +run each task individually: |
| 96 | + |
| 97 | +```bash |
| 98 | +$ gulp # Lint, build, and test |
| 99 | +$ gulp lint # Just lint |
| 100 | +$ gulp build # Just build |
| 101 | +$ gulp test # Just test |
| 102 | +``` |
| 103 | + |
| 104 | +### Running Tests |
| 105 | + |
| 106 | +There are two test suites: unit and integration. The unit test suite is intended to be run during |
| 107 | +development and the integration test suite is intended to be run before packaging up release |
| 108 | +candidates. |
| 109 | + |
| 110 | +To run the unit test suite: |
| 111 | + |
| 112 | +``` |
| 113 | +$ gulp # Lint, build, and run unit test suite |
| 114 | +``` |
| 115 | + |
| 116 | +To run the integration test suite: |
| 117 | + |
| 118 | +``` |
| 119 | +$ node test/integration # Run integration test suite |
| 120 | +``` |
| 121 | + |
| 122 | +The integration test suite requires you to generate a service account key JSON file for the |
| 123 | +**admin-sdks-test** Firebase project and save it to `test/resources/key.json`. You can generate this |
| 124 | +from the |
| 125 | +[**Service Accounts**](https://console.firebase.google.com/project/admin-sdks-test/settings/serviceaccounts/adminsdk) |
| 126 | +tab of that project's settings page. |
| 127 | + |
| 128 | +### Repo Organization |
| 129 | + |
| 130 | +Here are some highlights of the directory structure and notable source files |
| 131 | + |
| 132 | +* `src/` - Source directory, written in TypeScript. |
| 133 | + * `auth/` - Auth source files, including the user management, credential, and token generator |
| 134 | + APIs. |
| 135 | + * `database/` - Database source files, imported as a minified JavaScript file from a separate |
| 136 | + repo. |
| 137 | + * `messaging/` - Messaging source files, including the FCM send APIs. |
| 138 | + * `utils/` - Utilities for doing things such as sending requests, handling errors, and validating |
| 139 | + inputs. |
| 140 | + * `index.ts` - Main SDK entry point which registers the Firebase services. |
| 141 | + * `index.d.ts` - Hand-crafted TypeScript declaration file. |
| 142 | + * `firebase-app.ts` - `FirebaseApp` implementation. |
| 143 | + * `firebase-namespace.ts` - `FirebaseNamespace` implementation. |
| 144 | + * `default-namespace.ts` - Exports a `FirebaseNamespace` instance which acts as the top-level SDK |
| 145 | + export. |
| 146 | +* `lib/` - Output directory for all compiled files. |
| 147 | +* `test/` - Unit and integration test suites. |
| 148 | + * `unit/` - Unit test suite written in Mocha which extensively tests the source code using mocks |
| 149 | + for all network requests. |
| 150 | + * `index.spec.js` - Main unit test entry point which imports the tests to be run. |
| 151 | + * `utils.js` - Testing utilities. |
| 152 | + * `integration/` - Integration test suite which actually hits live Firebase services. |
| 153 | + * `resources/` - Provides mocks for several variables as well as mock service account keys. |
| 154 | +* `.github/` - Contribution instructions as well as issue and pull request templates. |
| 155 | +* `createReleaseTarball.sh` - Generates a new release tarball and ensures it passes all tests. |
| 156 | +* `gulpfile.js` - Defines the `gulp` tasks. |
| 157 | +* `tslint.json` - TypeScript linting rules. |
| 158 | +* `tsconfig.json` - TypeScript configuration options. |
0 commit comments