matrix-org / matrix-org/matrix-spec

Incorrect and unclear description of `prev_batch` usage for /sync

Open
#595 4 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

A-Client-Server clarification
Dominant language
HTML
Stars
330
Forks
150
Avg merge
2h 21m
Merged PRs (30d)
3

Description

From the spec:

Finally, the response includes, for each room, a prev_batch field, which can be passed as a start parameter to the /rooms/<room_id>/messages API to retrieve earlier messages.
[...]
prev_batch: A token that can be supplied to the from parameter of the rooms/{roomId}/messages endpoint.

Two issues with this:

  1. It's not clearly defined what dir one should request from /messages, using this prev_batch token
  2. There is no such thing as a start parameter, like the first part of the quoted text claims (there's only such a property in the response); presumably, that was supposed to say from rather than start.

Contributor guide

Open the contributing guide

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

Open the specification section linked in the issue and locate the /sync room prev_batch description alongside the rooms/{roomId}/messages parameter documentation. Check the parameter names and determine how the required dir value should be documented; done means the text is accurate and unambiguous.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.