User:Martyav/Deployment pipeline project user stories

From Wikitech

As a <blank>, I want to <blank> so I can <blank>.

Ordered roughly from most to least common use case, subject to amendment.

As an experienced developer, I need a quick link to the schedule, so I can know when to deploy a patch.

Bingo: Deployments

As an experienced dev, I want to grab some code samples, so I can perform some common tasks quickly.

There are code samples scattered here and there, with particularly relevant code on the Howto deploy X pages and on Event_Platform/EventGate/Administration. We could have a page containing (a table of?) code with light context describing when and why you would use it.

As an experienced dev, I need to find a how-to as a refresher.

We have How-To, and the category, How-To. Currently, the top section of How-To covers deployment. We should improve on this section rather than creating a new page to maintain.

Deploy how-to's:

As a new dev, I want to learn how to contribute code, so I can join Wikitech's open source community.

The pipeline primarily uses Gerrit. Mediawiki has several good pages describing how to join it and start submitting code.

It's important that newcomers know that while they can read source code on Github , they cannot submit pull requests there. Pull requests only come via Gerrit. This is also described on Mediawiki.

The Gerrit repo.

As a dev new to Wikitech, I want to learn how to sign up for Gerrit/developer account, etc., so I can work on the pipeline.

We actually have several nice pages covering in more or less detail how to get a developer account and various credentials for pipeline deployment work -- we should pick one and link to it, rather than adding even more.

Examples:

As a dev new to the pipeline, I need to know what tools we use, so I have clarity on what I need to learn about and what I don't.

A glossary is available, and we can flesh it out more. A page simply listing deployment tools, with a brief description and a link to the relevant page(s), would also be useful. Note that Wiki also uses tool to refer specifically to a bot/webservice/job that runs in Toolforge.

Tool pages & related:

Some of these pages are in a fairly mature state; others need wikilove. For example, Blubber has its own hub, but the Kubernetes page currently has a one sentence description followed by notes on debugging and administration. In particular, Helm is a stub with two links. Kubernetes/Helm has more info, and Event_Platform/EventGate/Administration#Production is a little more descriptive of what Helm is, as well as having code related to deployment.

Gaps

We should have a page (or a section on Helm) about charts.

Deployment involves local testing on with ab; User:Alexandros Kosiaris/Benchmarking kubernetes apps has a draft about it.

Culls

Having multiple pages describing the same thing often makes one or more of the pages less likely to be maintained, and then we wind up with articles that are stubby or out of date. Since in some cases, we have pages that overlap much more informative pages on Mediawiki, perhaps the versions on Wikitech should be culled. These include the Kubernetes and Docker pages.

As a dev new to the pipeline, I want to learn how the Kubernetes deployment system works, so I can understand what's going on when I deploy.

A new dev, and any visitor geeky enough to want to learn more about how the pipeline works, are probably at similar levels of knowledge, so we don't need to proliferate overview pages for different audiences. We already have deployment pipeline, which can be worked on to be more descriptive, or maybe MediaWiki_deployment_setup could be used, with a link to the deployment pipeline article in the intro. Graphics would be helpful for getting things across to readers ([1]).

As a dev new to the pipeline, I want to learn how to deploy, so I can be of service to the team.

Bingo: How_to_deploy_code.

Well...actually...Event_Platform/EventGate/Administration is also good, and covers some things the other page doesn't. What to do?

As a developer new to the pipeline, I want to understand how to minimize mistakes while deploying, so I can work smoothly without irritating my colleagues or blowing up the servers.

How_to_deploy_code and other pages with "common sense" sections covers this. Would it be redundant/not useful to have it as a separate guide?

As a dev new to the pipeline, I want to learn about the differences between deployment and SRE, because I'm not sure -- they seem related, but how?

Since SRE and deployment work closely, it can be a little confusing for a newcomer such as myself where one ends and the other begins. This might not need to be a separate page so much as incorporated into an overview describing how the teams at Wiki work and who is doing what.

There is also a team within deployment (SWAT), which should be mentioned somewhere.

As a techie visitor to the site, I want to find past articles describing older architecture and infrastructure.

We seem to have few outside visitors from the rest of the Wiki community, so anyone digging through the archives would likely to be another technical writer, or perhaps a dev searching for a key article on something that has been deprecated. In either case, the reader would have a higher technical background.

We have at least two categories specifically for that, plus any page with Obsolete or old in the title, the deployment archives, and even more at Mediawiki, as well as Quiddity's collection of old infographics and illustrations. With so much information, an overview would be nice, if we don't have already have a good page covering that.

However, this story should not be prioritized over more common use cases.

Rough portal outline

Title — Portal:Deployment pipeline

Brief explanatory text about the pipeline

  1. Overview: #As a dev new to the pipeline, I want to learn how the Kubernetes deployment system works, so I can understand what's going on when I deploy., #As a dev new to the pipeline, I need to know what tools we use, so I have clarity on what I need to learn about and what I don't.
  2. Schedule: #As an experienced developer, I need a quick link to the schedule, so I can know when to deploy a patch.
  3. How-To's: #As a dev new to the pipeline, I want to learn how to deploy, so I can be of service to the team., #As an experienced dev, I need to find a how-to as a refresher.
  4. Code samples: Not sure if this section is necessary. #As an experienced dev, I want to grab some code samples, so I can perform some common tasks quickly.
  5. Sign up: #As a dev new to Wikitech, I want to learn how to sign up for Gerrit/developer account, etc., so I can work on the pipeline.
  6. Contribute to our open source community: #As a new dev, I want to learn how to contribute code, so I can join Wikitech's open source community.
  7. Tools: #As a dev new to the pipeline, I need to know what tools we use, so I have clarity on what I need to learn about and what I don't.
  8. Concepts: #As a dev new to the pipeline, I want to learn how the Kubernetes deployment system works, so I can understand what's going on when I deploy., #As a dev new to the pipeline, I want to learn about the differences between deployment and SRE, because I'm not sure -- they seem related, but how?, maybe even parts of #As a dev new to the pipeline, I need to know what tools we use, so I have clarity on what I need to learn about and what I don't. that need to be gone into more in-depth...so lots of cross-linking to and from this section of the portal. How do we break it down?
  9. Archives: #As a techie visitor to the site, I want to learn more about past architectures and documents, because I find it historically interesting.

General notes

There will be natural overlap with existing and developing portal pages, such as Portal:Toolforge and Help:Glossary, and even with pages on outside sites, such as Mediawiki. This will be useful, as fewer pages to maintain means fewer things get neglected.

There is a wealth of information already written, but some of it is hidden within subpages, which makes it less visible. For example, Help:Glossary is mostly linked to by other pages within the Toolforge portal.

Other pages, especially those relating to Kubernetes, need creation or additional fleshing out.

There are categories we can use for our lists, but the categories themselves are kind of a hodgepodge, and there needs to be some tagging.

Retrieved from "https://wikitech.wikimedia.org/w/index.php?title=User:Martyav/Deployment_pipeline_project_user_stories&oldid=1825132"