Core Platform Team/PET Work Processes/PET Ideal User Story

Overview
Here we cover what the general outline of an optimal User Story that meets the Core Platform Team's Platform Intake Standards.

The outline is based on an existing task, T252202, that was built using a TDD process involving Product and Engineering breaking down the user story together and focusing on atomic level work.

This document will be refined and updated as our User Story process improve.

Approach
The goal of a User Story is two fold. First, to deliver clear enough value upon completion that furthers the objective of an overarching Epic. Second, to be atomic enough to represent a single unit of work to complete.

Our initial User Story was: "As a Contributor, I want to get a list of revisions that I have made, to get a sense of the scale and importance of my own work."

Our goal was to break this work down into a consistent actionable structure

Example Ideal User Story
Story

"As a Contributor, I want to get a list of revisions that I have made, to get a sense of the scale and importance of my own work."

A rough equivalent of the user contributions page in REST form. Compare T235073, which gets the contributions for other users.

Done Criteria

[ ] A non-logged-in client will receive a Status 401 Patch

[ ] Returns a list of N page revisions by the current logged-in user [ ] Suppressed revisions are not exposed to unauthorized users, but visible to authorized users Patch Client should be able to request the next (earlier in time) segments The response should contain the following properties: Patch
 * Response object must be JSON
 * Response object must contain the following fields:
 * Revisions: an array of 0 to segment_size limit revision objects, each with the following information:
 * id: revision id
 * comment: edit summary of the change, provided by the user
 * timestamp: date of change, YYYY-MM-DDTHH:MM:SSZ
 * size: count of bytes
 * page: Page that was modified, JSON object with the following properties: {id, key, title} (see the schema for details)

"older": Full link to API endpoint + "before|" + rev ID or rev timestamp. May be null if there are no known older revisions. Client should be able to request the previous (later in time) segments. The response should contain the following properties: Patch "older": Full link to API endpoint + "before|" + rev ID or rev timestamp. May be null if there are no known older revisions. "newer": Full link to API endpoint + "after|" + rev ID or rev timestamp "latest": Full link to API endpoint without parameters There is a stable chronological order among the revisions, based on the combination of revision ID AND revision timestamp Patch Each revision should also have the field: delta: +/- count of bytes changed from previous Patch Each revision should also have the field: tags: array of Tag objects with [ tag, url ], per schema Patch Designs/Interface/Mockups

GET /me/contributions?segment=&limit=

Segmented contribution history by user with name name. (I'm calling it "segmented" instead of "paged" so we don't all go crazy.)

segment_marker: ( "before" | "after" ) "|" timestamp "|" revision_id segment_size: size of the segment to get; minimum is 1, default is 20, and maximum 100

Request body: none

Notable request headers: none

Status: 200 - OK 401 - not authenticated 400 - invalid segment marker or segment size is out of bounds

Notable response headers: none

Body: JSON, an object with the following fields: older: full link to API endpoint for the next older segment of results. oldest segment will have this field null. all other segments will have a value. newer: full link to API endpoint for the next newer segment of results. This will never be null (to account for edits occurring after we get results) latest: full link to API endpoint for the latest values, usually just this endpoint with no parameters revisions: an array of 0 to 20 revision objects, in reverse chronological order, each with the following information: id: revision id comment: edit summary of the change, provided by the user timestamp: date of change, YYYY-MM-DDTHH:MM:SSZ delta: +/- count of bogobytes changed from previous size: count of bogobytes page: Page that was modified, JSON object with the following properties: {id, key, title} (see schema for details) tags: array of Tag objects (see schema)

Related Stories

"As a Reader, I want to get a list of revisions of pages a Contributor has created or updated, because I want to read more of what they have written."

"As a Contributor, I want to get a list of revisions of pages another Contributor has created or updated, because I want to contribute to pages that are similar to ones that I've collaborated on with that person."

"As a Curator, I want to get a list of revisions of pages a Contributor has created or updated, because they may have made a repeated mistake on multiple pages."

Example Ideal User Story
Based on the Allen meeting last week I'd like to discuss this a little. He made very clear that the stories need to be as atomic and valuable as possible. So completing a story should be a single piece of work, that is valuable so it should ship immediately.

This allows us to give continuous delivery on projects. Practically, speaking I think the org actually already does this by merging to master and straight onto the train.

It means though that our feedback cycle with other teams should be really tight, and likely we should be matrixing either us into them or them into us.