Updated developer docs (#1798)
This commit is contained in:
Jason Robbins
GitHub
Родитель
0aa2b3cfc9
Коммит
9b420b811b
10
README.md
10
README.md
|
|
@ -33,7 +33,7 @@ You will need to activate the venv in every shell that you use.
|
|||
1. `source cs-env/bin/activate`
|
||||
|
||||
|
||||
If you face any error during the installation process, the section **Notes** (later in this README.md) may help.
|
||||
If you encounter any error during the installation process, the section **Notes** (later in this README.md) may help.
|
||||
|
||||
##### Add env_vars.yaml
|
||||
|
||||
|
|
@ -81,12 +81,14 @@ There are some developing information in developer-documentation.md.
|
|||
|
||||
- If you get an error saying `No module named protobuf` or `No module named six` or `No module named enum` , try installing them locally with `pip install six enum34 protobuf`.
|
||||
|
||||
- When installing the GAE SDK, make sure to get the version for python 2.7. It is no longer the default version.
|
||||
- When installing the GAE SDK, make sure to get the version for python 3.
|
||||
|
||||
- If you run the server locally, and then you are disconnected from your terminial window, the jobs might remain running which will prevent you from starting the server again. To work around this, use `ps aux | grep gunicorn` and then use the unix `kill -9` command to terminate those jobs.
|
||||
|
||||
|
||||
#### Blink components
|
||||
|
||||
Chromestatus gets the list of Blink components from a separate [app running on Firebase](https://blinkcomponents-b48b5.firebaseapp.com/blinkcomponents). See [source](https://github.com/ebidel/blink-components).
|
||||
Chromestatus currently gets the list of Blink components from the file `hack_components.py`.
|
||||
|
||||
#### Seed the blink component owners
|
||||
|
||||
|
|
@ -127,7 +129,7 @@ The production site should only have versions that match versions on staging.
|
|||
|
||||
### LICENSE
|
||||
|
||||
Copyright (c) 2013-2016 Google Inc. All rights reserved.
|
||||
Copyright (c) 2013-2022 Google Inc. All rights reserved.
|
||||
|
||||
Apache2 License.
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,9 @@
|
|||
|
||||
This doc covers some basic overview of the codebase to help developers navigate.
|
||||
|
||||
In summary, this web app is using a combination of Django & Flask as the backend and lit-element in the front end. It uses [Google Sign-In](https://developers.google.com/identity/sign-in/web/sign-in) for authentication. **Google Cloud Datastore** is used as database.
|
||||
In summary, this web app is using a combination of Django & Flask as the backend and uses Lit webcomponents in the front end.
|
||||
It uses [Sign in with Google](https://developers.google.com/identity/gsi/web) for authentication.
|
||||
**Google Cloud Datastore** is used as database.
|
||||
|
||||
## Back end
|
||||
|
||||
|
|
@ -27,26 +29,22 @@ All the pages are rendered in a combination of Django template (`/templates`) an
|
|||
- The folder organization and template file names matches the router. (See `template_path=os.path.join(path + '.html')` in `server.py`)
|
||||
- lit-element components, css, js files are all imported/included in those templates.
|
||||
- We pass backend variables to js like this: `const variableInJs = {{variable_in_template|safe}}`.
|
||||
1. All lit-element components are in `/static/elements`.
|
||||
1. All Lit components are in `/static/elements`.
|
||||
1. All JavaScript files are in `/static/js-src/` and processed by gulp, then output to '/static/js/' and get included in templates.
|
||||
1. All CSS files are in `/static/sass/` and processed by gulp, then output to `/static/css/` and get included in templates.
|
||||
|
||||
|
||||
## Creating a user with admin privileges
|
||||
To create or edit features, you must log in using an email which has admin privileges. An email has admin privileges if it is stored in the Datastore with `is_admin` property set to `True`. To create an admin user for your local installation follow these steps:-
|
||||
1. Access Admin Server using the url mentioned in the command line output of `npm start`.
|
||||
1. Click on interactive console and execute the following query:-
|
||||
```
|
||||
from google.cloud import ndb
|
||||
from internals import models
|
||||
|
||||
client = ndb.Client()
|
||||
with client.context():
|
||||
appuser_1 = models.AppUser(email='your_account@domain_name.tld', is_admin=True)
|
||||
appuser_1.put()
|
||||
Creating or editing features normally requires a `@google.com` or `@chromium.org` account.
|
||||
To work around this when running locally, you can make a temporary change to the file `framework/permissions.py` to
|
||||
make function `can_admin_site()` return `True`.
|
||||
Once you restart the server and log in using any account, you will be able create or edit features.
|
||||
|
||||
To avoid needing to make this temporary change more than once, you can sign in
|
||||
and visit `/admin/users/new` to create a new registered account using the email
|
||||
address of any Google account that you own, such as an `@gmail.com` account.
|
||||
|
||||
```
|
||||
To view and edit the users datastore, you can click on Datastore Viewer. Make sure that `Entity Kind` is set to `AppUser`.
|
||||
|
||||
## Generating Diffs for sending emails to subscribers of a feature
|
||||
* When someone edits a feature, everyone who have subscribed to that feature will receive a email stating what fields were edited, the old values and the new values.
|
||||
|
|
@ -58,163 +56,5 @@ To view and edit the users datastore, you can click on Datastore Viewer. Make su
|
|||
1. On pressing submit after editing the feature, you will be able to see the diff in the console logs.
|
||||
|
||||
## Local Development
|
||||
* When run locally, Datastore Emulator is used for storing all the entries. To check the entries present in the DataStore emulator, access the admin server using the url mentioned in the command line output of `npm start` and click on `Datastore Viewer` button.
|
||||
* Executing `npm start` runs `dev_appserver.py` which automatically starts the Datastore Emulator. Hence, we do not have to start it explicitly. However, when running unittests, we will have to start the Datastore Emulator manually using `npm run start-emulator`.
|
||||
* `npm run test` will first reset the datastore emulator and then run the tests.
|
||||
* To stop the emulator, use `npm run stop-emulator`. You do not have to stop and start the Datastore Emulator between consecutive runs of `npm run test`.
|
||||
|
||||
## Some nice-to-fix
|
||||
|
||||
- Wrap page in a component, so the data flow is more clear. Benefits: no need to assigns component properties from js files; no need to pass element reference to components to get value (e.g. we are passing searchEl to chromedash-featurelist.).
|
||||
- Some buttons are a / span / div.
|
||||
|
||||
## Content from the old developer doc (some are out-of-date)
|
||||
|
||||
** index.html
|
||||
*
|
||||
* The 'Most Popular' page.
|
||||
*
|
||||
* This file is to show 10 charts. They will be charts from
|
||||
* the top 10 Properties of the stack rank page.
|
||||
*
|
||||
* This implementation is not complete.
|
||||
* This depends upon stack rank.
|
||||
*
|
||||
**
|
||||
|
||||
** stackrank.html
|
||||
*
|
||||
* Lists all properties from highest popularity to least
|
||||
* User may reverse order
|
||||
*
|
||||
* Will function, once a date is specified in QueryStackRank of main.py
|
||||
*
|
||||
**
|
||||
|
||||
** main.py
|
||||
*
|
||||
* Handler File
|
||||
*
|
||||
* /data/querystableinstances performs a query to get all instances
|
||||
* from the database. This data is converted to JSON and written to
|
||||
* the page.
|
||||
*
|
||||
* /data/querystackrank performs a query to get most recent day's
|
||||
* popularity rank in default descending order. The data is converted to
|
||||
* JSON and written to the page.
|
||||
*
|
||||
**
|
||||
|
||||
** admin.py
|
||||
*
|
||||
* Handler File
|
||||
*
|
||||
* visiting /cron/metrics calls YesterdayHandler which retrieves yesterday's data from the UMA Cloud Storage.
|
||||
* This is how the cron job is updating - Daily grabbing the previous day's data
|
||||
* The data is parsed and stored as:
|
||||
* class StableInstance(DictModel):
|
||||
* property_name = db.StringProperty();
|
||||
* bucket_id = db.IntegerProperty();
|
||||
* date = db.DateProperty();
|
||||
* day_percentage = db.FloatProperty();
|
||||
* rolling_percentage = db.FloatProperty();
|
||||
*
|
||||
* visiting /cron/histograms calls HistogramsHandler which retrieves FeatureObserver and
|
||||
* FeatureObserver histograms from chromium.googlesource.com.
|
||||
*
|
||||
* ACTION REQUIRED: we will need to replace histogramID with the appropriate ID.
|
||||
* This can be obtained from uma.googleplex.com/data/histograms/ids-chrome-histograms.txt
|
||||
* Searching this file for CSS Properties, once our histogram has data should give us a hex
|
||||
* value which should be converted to an integer.
|
||||
*
|
||||
*
|
||||
|
||||
|
||||
** featurelevel.js
|
||||
*
|
||||
* Creates charts for the feature level page.
|
||||
*
|
||||
* drawVisualization()
|
||||
* This function takes in the name of the property for which the graph is being drawn.
|
||||
* (This should probably be changed to the propertyID/bucketID in the future.)
|
||||
* We iterate through parsed data, building up a data object which we can pass to chart.draw()
|
||||
* The desired form of data to pass to chart.draw() is:
|
||||
* [[Date, Name, Percentage]
|
||||
* [Mar 3, Color, 60]
|
||||
* [Mar 4, Width, 70]]
|
||||
* ** If we need to look into further optimization, building this data structure is probably the place it can happen.
|
||||
*
|
||||
* getNamesArray()
|
||||
* Takes the desired name to have displayed on the chart. Checks if there is a correspinding property (prefixed or unprefixed)
|
||||
* adds the given name plus the corresponding name to an array and returns the array.
|
||||
*
|
||||
**
|
||||
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
OPTIMIZATIONS
|
||||
- show/hide less of panel when user clicks it
|
||||
- recalc style issue perf in chrome 28 (https://src.chromium.org/viewvc/blink?revision=150018&view=revision)
|
||||
-> turn on shadow dom polyfill for stable (e.g. Platform = {flags: {shadow: 'polyfill'}};)
|
||||
- insertBefore issue being fixed: https://code.google.com/p/chromium/issues/detail?id=255734.
|
||||
-> Remove inline <style> in elements.
|
||||
- Calculate a property in a *Changed handler rather than getters. Latter sets
|
||||
up timers if o.Observe() is not present. Former is only calculated once when
|
||||
the prop changes.
|
||||
|
||||
load features from server. could have also done ajax
|
||||
|
||||
elements talk to each other through events and passing chromemetadata in
|
||||
|
||||
color-status does its thing. repurposed in mulitple places
|
||||
|
||||
chrome-metadata that does auto ajax
|
||||
|
||||
render list of features on a filtered view, not entire list.
|
||||
|
||||
ajax-delete link element is pretty coo
|
||||
|
||||
sass workflow
|
||||
|
||||
added tabindex=0 to features so they can be a11yn
|
||||
|
||||
dont publish opened in chromedash-feature. Property reflection to attributes
|
||||
redistribute entire thing in SD polyfill. https://github.com/Polymer/polymer/issues/236
|
||||
|
||||
Way sass was written, selectors match from right to left. So *:hover matched
|
||||
all elements in SD, then filtered on :hover. Change was to be more specific and add tag:
|
||||
|
||||
.views {
|
||||
@include display-flex;
|
||||
@include flex-wrap(wrap);
|
||||
|
||||
& > span { // was & > * {
|
||||
@include display-flex;
|
||||
@include align-items(center);
|
||||
position: relative;
|
||||
...
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
|
||||
the css in ericbidelman's app is the issue
|
||||
lots of very complex selectors
|
||||
ex. chromedash-feature section .views > :hover::before
|
||||
we match from right to left, which means that can "match" <html>
|
||||
or any descendants
|
||||
so now hovering anything on that page recalcs style the entire document
|
||||
same thing with tapping tapping
|
||||
chromedash-feature section .views > :active::before
|
||||
|
||||
the rest of the slow recalcs are [data-first-of-milestone]:first-of-type { ... } in the css for <chromedash-featurelist>
|
||||
tapping to expand a single row triggers the "invalidate style on all my siblings because of complex selectors" case in Element::recalcStyle
|
||||
|
||||
Solution was to remove one selector.
|
||||
|
||||
&:first-of-type {
|
||||
margin-top: $milestone-label-size + 2;
|
||||
}
|
||||
* When run locally, Datastore Emulator is used for storing all the entries.
|
||||
* Executing `npm start` or `npm test` automatically starts the Datastore Emulator and shuts it down afterwards.
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче