|
| 1 | +<h2>Table of contents</h2> |
| 2 | + |
| 3 | +- [General contributor notes](#general-contributor-notes) |
| 4 | + - [`feast ui` command](#feast-ui-command) |
| 5 | + - [NPM package project structure](#npm-package-project-structure) |
| 6 | + - [Tests](#tests) |
| 7 | + - [Yarn commands](#yarn-commands) |
| 8 | + - [`yarn install`](#yarn-install) |
| 9 | + - [`yarn start`](#yarn-start) |
| 10 | + - [`yarn test`](#yarn-test) |
| 11 | +- [Release process](#release-process) |
| 12 | + - [(Advanced) Manually publishing the Feast Package to NPM](#advanced-manually-publishing-the-feast-package-to-npm) |
| 13 | + - [Requirements](#requirements) |
| 14 | + - [Steps for Publishing](#steps-for-publishing) |
| 15 | + |
| 16 | +# General contributor notes |
| 17 | +In this doc, we describe how to contribute both to the Feast Web UI NPM package as well as the embedded Feast UI in the Python SDK (i.e. what's run when you run `feast ui`) |
| 18 | + |
| 19 | +## `feast ui` command |
| 20 | +You can see the logic in [../sdk/python/feast/ui](../sdk/python/feast/ui/). This instance is loaded in [../sdk/python/feast/ui_server.py](../sdk/python/feast/ui_server.py). |
| 21 | + |
| 22 | +Under the hood, what happens is that the Feast SDK spins up a server which exposes an endpoint to the registry. It then mounts the UI on the server and points it to fetch data from that registry. |
| 23 | + |
| 24 | +## NPM package project structure |
| 25 | +The Web UI is powered by a JSON registry dump from Feast (running `feast registry-dump`). Running `yarn start` launches a UI |
| 26 | +powered by test data. |
| 27 | +- `public/` contains assets as well as demo data loaded by the Web UI. |
| 28 | + - There is a `projects-list.json` which represents all Feast projects the UI shows. |
| 29 | + - There is also a `registry.json` which is the registry dump for the feature repo. |
| 30 | +- `feature_repo/` contains a sample Feast repo which generates the `registry.json` |
| 31 | +- `src/` contains the Web UI source code. |
| 32 | + - `src/contexts` has React context objects around project level metadata or registry path metadata to inject into pages. The contexts are static contexts provided by [FeastUISansProviders.tsx](src/FeastUISansProviders.tsx) |
| 33 | + - `src/parsers` parses the `registry.json` into in memory representations of Feast objects (feature views, data sources, entities, feature services). |
| 34 | + - This has ~1:1 mappings to the protobuf objects in [feast/protos/feast/core](https://github.com/feast-dev/feast/tree/master/protos/feast/core). |
| 35 | + - There are also "relationships" which create an in-memory lineage graph which can be used to construct links in pages. |
| 36 | + - This generates state which pages will load via React queries (to the registry path). |
| 37 | + - `src/pages` has all individual web pages and their layouts. For any given Feast object (e.g. entity), there exist: |
| 38 | + - an **Index page** (which is the first page you hit when you click on that object). This loads using a React query the in memory representation of all objects (parsed from `src/parsers`) and embeds: |
| 39 | + - a **Listing page** (i.e. listing all the objects in the registry in a table). This creates links to the instance pages |
| 40 | + - an **Instance page** (which shows details for an individual entity, feature view, etc). This embeds: |
| 41 | + - a default Overview tab, which shows all the Feast metadata (e.g. for a given entity) |
| 42 | + - custom tabs from `src/custom-tabs`. |
| 43 | + - Other subdirectories: |
| 44 | + - `src/components` has common React components that are re-used across pages |
| 45 | + - `src/custom-tabs` houses custom tabs and a custom tab React context which exist on the core pages. There is a `TabsRegistryContext` which is also supplied by the [FeastUISansProviders.tsx](src/FeastUISansProviders.tsx), and if there are custom tabs, the Feast UI will embed them as a new tab in the corresponding page (e.g. feature view page). |
| 46 | + - `src/graphics` houses icons that are used throughout the UI |
| 47 | + - `src/hooks` has React hooks. The most complex hooks here define the bulk of the search / filter functionality. |
| 48 | + |
| 49 | +## Tests |
| 50 | +There are very few tests for this UI. There is a smoke test that ensures pages can load in [FeastUISansProviders.test.tsx](src/FeastUISansProviders.test.tsx) |
| 51 | + |
| 52 | + |
| 53 | +## Yarn commands |
| 54 | + |
| 55 | +If you would like to simply try things out and see how the UI works, you can simply run the code in this repo. First: |
| 56 | + |
| 57 | +### `yarn install` |
| 58 | + |
| 59 | +That will install the all the dependencies that the UI needs, as well as development dependencies. Then in the project directory, you can run: |
| 60 | + |
| 61 | +### `yarn start` |
| 62 | + |
| 63 | +Runs the app in the development mode.\ |
| 64 | +Open [http://localhost:3000](http://localhost:3000) to view it in the browser. |
| 65 | + |
| 66 | +The page will reload if you make edits.\ |
| 67 | +You will also see any lint errors in the console. |
| 68 | + |
| 69 | +### `yarn test` |
| 70 | + |
| 71 | +Launches the test runner in the interactive watch mode.\ |
| 72 | +See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information. |
| 73 | + |
| 74 | +# Release process |
| 75 | +There are a couple of components in Feast that are tied to the Web UI. These are all automatically handled during the release GitHub action: |
| 76 | +1. the npm package |
| 77 | + - The release process for Feast automatically bumps the package version (see [bump_file_versions.py](../infra/scripts/release/bump_file_versions.py)) and releases the new NPM package (see [publish.yml](../.github/workflows/publish.yml) in the `publish-web-ui-npm` job) |
| 78 | +2. the Feast Python SDK, which bundles in a compiled version of the Feast Web UI which is run on a `feast ui` CLI command. |
| 79 | + - The bundled Web UI in the Python SDK always compiles in the latest npm version |
| 80 | + |
| 81 | +## (Advanced) Manually publishing the Feast Package to NPM |
| 82 | + |
| 83 | +This generally should not be necessary, since new package versions are released with the overall Feast release workflow (see [publish.yml](../.github/workflows/publish.yml) in the `publish-web-ui-npm` job) |
| 84 | + |
| 85 | +The Feast UI is published as a module to NPM and can be found here: https://www.npmjs.com/package/@feast-dev/feast-ui |
| 86 | + |
| 87 | +### Requirements |
| 88 | + |
| 89 | +To publish a new version of the module, you will need: |
| 90 | +- to be part of the @feast-dev team in NPM. Ask `#feast-development` on http://slack.feast.dev to add you if necessary. |
| 91 | +- to [login to your NPM account on the command line](https://docs.npmjs.com/cli/v8/commands/npm-adduser). |
| 92 | + |
| 93 | +### Steps for Publishing |
| 94 | + |
| 95 | +1. Make sure tests are passing. Run tests with `yarn test` in the ui directory. |
| 96 | +2. Bump the version number in `package.json` as appropriate. |
| 97 | +3. Package the modules for distributions. Run the library build script with `yarn build:lib`. We use [Rollup](https://rollupjs.org/) for building the module, and the configs are in the `rollup.config.js` file. |
| 98 | +4. Publish the package to NPM. Run `npm publish` |
| 99 | +5. [Check NPM to see that the package was properly published](https://www.npmjs.com/package/@feast-dev/feast-ui). |
0 commit comments