MediaWiki

Docker/SIG/Meetings/20190304 - Docs

< Docker | SIG

Discussion: Dev environment docs for new users

edit

A discussion following from initial Docker SIG meeting.

Participants: Eric Gardner, Hana Worku, Jeena Huneidi, Brennen Bearnes

From the invite:

Per conversation in the Docker SIG kickoff meeting, there's some agreement that documentation on environments for new developers (Docker-based and otherwise) is fragmented at the moment and there's not necessarily a clear funnel / entry point.

Let's chat about how to improve that situation, maybe starting with identifying the use cases we want to cover, as well as how it relates to current dev environment efforts like local-charts. I'll make an effort to have a better handle on the existing docs and share some summary notes.

Existing documentation

edit

General:

Environment-specific:

What is this list missing?

Discussion

edit

What's our goal for this discussion?

  • Eric: An entry point for people who are getting starting with Docker.
    • Docker's a good approach for people who're new.
    • We have that for MW-Vagrant, would be nice to have some of the same for Docker.
    • Right now we point people to addshore's repo, but that's not the same as having a hub of info for getting started.
  • Brennen: MW-Vagrant page is a good model for this?
  • Jeena: There's so many pages. Kind of confusing and frustrating to have to go through so much stuff.
  • Eric: Same.
  • Eric: One thing I think is good about Vagrant documentation is the whole role system - "I need to add this component, here's the role."
    • We may not need to aspire to that level of automation, but there's not a lot of docs on mw-docker-dev for adding stuff to that docker-compose setup.
    • Cookbook-style recipes for how to provide various things.
    • A more modular approach.
  • Jeena: The stuff we're working on now is kind of in-between those two approaches. Ideally, you just have to change a little bit of config to say what you want to set up.
    • Going back to Vagrant documentation, it does look pretty extensive, but having it outside of the repo means that it's harder for it to stay up to date.
  • Jeena: Maybe it'd be good if wiki stuff could point out to canonical stuff in repos.

Discussion of relationship between mediawiki-docker-dev & local-charts

  • local-charts lives in k8s land conceptually

Digression (useful) on experience of starting up with Vagrant, mediawiki-docker-dev:

  • Eric: In Vagrant, initial startup was easy, but more complex stuff became overwhelming
  • Hana: Cirrus search on Vagrant - neither of us were able to get that working easily
    • Requires ElasticSearch
  • Eric: Multimedia team's use case is probably a good example - WikiBase media info extension (sp?) - chain of dependencies that need to be configured just so for local development. There're probably a lot of similar cases, i.e., VisualEditor
  • Jeena: VisualEditor should just run now on local-charts
  • Eric: Redis
  • Hana: It's weird that there're so many docs. For people who just want to onboard to their teams, there should be a much more succinct, vetted, maintained place. You can have choices, but here's a known-good way that it works. It was a struggle to find that. Jumping all over the place. Whatever the doc is, making sure it's reflective of what we actually want folks to do.
  • Jeena: Yeah, I don't know that there's a standard.
  • Eric: That's why I was thinking of a recipe based system.
    • With both vagrant and addshore's repo, it was stepping outside of the baseline thing that became difficult.
    • Commonly-defined blockers.
  • Hana: More discussion, more holistic coordination around things like vagrant roles (or their conceptual equivalent).
  • Jeena: Developers shouldn't have to do so much extra work on top of their extensions, etc., i.e., shouldn't have to define vagrant stuff, if we set things up correctly.
  • Eric: How much knowledge about Docker etc. do we want to assume people have? Basic intro material would be useful.
    • Brennen: We probably shouldn't assume too much, should point people at intro material, not sure how much of that class of documentation we want to own ourselves.

Back to outcomes of this discussion:

  • Jeena: Define a location (a page) to work on.
  • Eric: Can we can create a draft page for working on this?
  • Brennen: Yeah, we could probably define a sandbox under the Docker SIG page for roughing some stuff out.
  • Brennen TODO: Phabricator task, create a sandbox area for roughing out some material.
  • Specific things to provide
    • Hana: Knowing where to ask questions is hard to do. We have a lot of different ways people are spinning things up. Maybe we should point people to an IRC channel.
      • Jeena: Make sure it's not invite only.
    • Include info about Docker SIG.
Retrieved from "https://www.mediawiki.org/w/index.php?title=Docker/SIG/Meetings/20190304_-_Docs&oldid=3124742"