oppia / oppia/oppia-web-developer-docs
Add wiki documentation about index.yaml
Nobody has claimed this yet.
- 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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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