oppia / oppia/oppia-web-developer-docs

Add wiki documentation about index.yaml

Open
#152 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement Impact: Medium Work: Low
Dominant language
Python
Stars
18
Forks
133
PR merge metrics
No merged PRs in 30d

Description

Having the correct indices in the index.yaml file is a prerequisite for deployment, but the update flow for this file is unlikely to be clear to new contributors. It's detailed here: https://cloud.google.com/appengine/docs/flexible/configuring-datastore-indexes-with-index-yaml?tab=python

This can result in contributors getting edits in their index.yaml file that they didn't put there, and not knowing what to do with them. We don't seem to mention this gotcha at all in the wiki. Perhaps we should add an index.yaml page in the developer reference in the sidebar so that if a contributor runs into this issue they have some idea of what to do. (See e.g. https://github.com/oppia/oppia/pull/17742 for an example of this happening in practice.)

Ideally, the wiki page would explain:

  • what index.yaml is and what it's used for
  • what sorts of datastore queries will require updates to index.yaml, and which don't
  • what developers should do in index.yaml when adding a new multi-field datastore query

Note: When writing this page, please ensure that you test the flows locally by trying out appropriate changes on the oppia/oppia repo. If you'd like to take this issue up, explain in your comment what the instructions for the last two points above are, and how you verified those instructions.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the linked Google Cloud index.yaml documentation and the example in oppia/oppia#17742. Plan the developer-reference wiki page and its sidebar entry around what index.yaml does, which datastore queries require changes, and how to handle new multi-field queries. Verify the last two instructions locally in the oppia/oppia repository and document how they were checked.

Written by the indexing model from the issue text.

Assessment

Tech stack
gcp, python
Domain
databases, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.