This page walks through the process of updating the SearchSatisfaction schema in the modern Event Platform system, as it's one of the first schemas ported from the legacy EventLogging system (based on meta wiki) to the new git-based repository. For an example of a patch, please refer to 621473.
- NodeJS v10 or greater, so the current LTS release (v12.19.0) is fine
- This will also install
npm, which we need
- This will also install
- git-review (on Macs this is easiest with Homebrew and
brew install git-review)
- Cloned schemas/event/secondary repository
- Gerrit config
- Create an SSH key pair and upload the public key to your Gerrit account settings at https://gerrit.wikimedia.org/r/settings/#SSHKeys
- Add the following to your ~/.ssh/config:Replacing the values for
Host gerrit Hostname gerrit.wikimedia.org Port 29418 User bearloga IdentityFile ~/.ssh/gerrit_ed25519 Host gerrit.wikimedia.org Hostname gerrit.wikimedia.org Port 29418 User bearloga IdentityFile ~/.ssh/gerrit_ed25519
IdentityFileto values specific to you
Navigate to the cloned repository and run
npm install to install jsonschema-tools and the pre-commit hook for schema materialization.
You should see a message like
Saving jsonschema-tools materialize-modified pre-commit hook to /Users/mpopov/Desktop/temporary/secondary/.git/hooks/pre-commit
somewhere in there.
Open jsonschema/analytics/legacy/searchsatisfaction/current.yaml in your favorite text editor. We'll be adding a new boolean field to the schema called
coinFlipTail. There are many other types of fields supported by JSONSchema.
First, we bump the schema version up at the top of the file:
# Old: $id: /analytics/legacy/searchsatisfaction/1.2.0 # New: $id: /analytics/legacy/searchsatisfaction/1.3.0
Then we add the field itself at the bottom:
# ... schema metadata ... allOf: - $ref: /fragment/analytics/legacy/eventcapsule/1.1.0# - required: - event properties: event: type: object required: - action - searchSessionId - pageViewId - scroll - mwSessionId - source - uniqueId properties: action: type: string # ... more fields like searchToken, extraParams, skinVersion, etc. ... # ======= NEW FIELD WE'RE ADDING: ======== coinFlipTail: type: boolean description: >- The result of a random coin flip at the time of the event.
Make sure that the indentation is done with 2 spaces, otherwise you'll get validation errors. Once done, track & commit the changes:
git add -A git commit -m "Added coinFlipTail field to Search Satisfaction legacy schema"
You should then see messages about latest symlinks having been created and that "New schema files have been materialized."
npm test to verify that there are no errors before uploading to Gerrit for code review via
Once uploaded for review, add Bearloga or Ottomata as reviewer(s).
Sometimes you may need to make modifications that require manually re-materializing a schema. This is accomplished any time by:
./node_modules/.bin/jsonschema-tools materialize jsonschema/analytics/legacy/searchsatisfaction/current.yaml
Indeed, that is essentially what gets run automatically for you by the installed pre-commit hook.