search

jupyterhub / team-compass

A repository for team interaction, syncing, and handling meeting notes across the JupyterHub ecosystem.
http://jupyterhub-team-compass.readthedocs.io
62 stars 33 forks source link

Proposal: ROADMAPs #70

Open choldgraf opened 5 years ago

choldgraf commented 5 years ago

Hey all - we've had a few conversations around how to signal to the community what's "interesting" or "in-scope" for the JuypterHub project. Sometimes this is technical stuff, sometimes these are particular use-cases, etc.

I propose that we adopt a roadmap for a subset of the JupyterHub projects. I'm gonna spit-ball an idea here, and would love comments on what this looks like.

Current state of this issue

We've moved over the JupyterHub roadmap and created one for repo2docker as well. Those will show up soon on the jupyterhub roadmaps page soon.

We've also got issues to discuss roadmaps for Z2JH (https://github.com/jupyterhub/zero-to-jupyterhub-k8s/issues/1026) and BinderHub (https://github.com/jupyterhub/binderhub/issues/732).

Historical conversation ## Historical context It looks like the Jupyter project used to keep track of ROADMAPs [at this repo](https://github.com/jupyter/roadmap/). This is a single repository with one roadmap for a semi-arbitrary list of projects. Each one gets their own `.md` file and as far as I can tell, the projects are left to update (or not) those roadmaps as they see fit. [Here is JupyterHub's current roadmap in this org](https://github.com/jupyter/roadmap/blob/master/jupyterhub.md). ## A proposal I propose that the JupyterHub team moves their roadmap into one (or multiple) JupyterHub repositories. I think that this will make them more visible within the JupyterHub community, and will also make the more maintainable over the long run. ### Roadmap file structure We can still use markdown for the roadmap structure, perhaps calling it `ROADMAP.md`. It would exist in the root of the repository, and could be included in the documentation of repos with a sym-link + recommonmark for the Sphinx builds. ### Roadmap content The main goal of the roadmap is to signal to the community where the project's high-level interests lie. It's meant to be a "this is stuff we'd love to do, please help out if you'd like it too!" document, as opposed to a "this is stuff we will deliver" document. The roadmap *could* have dates on it if the community wants this, but it is not a "promise of work" by any means. E.g. some of the Jupyter projects were using "short", "medium", "long-term" which seemed to work OK. Over time, the roadmaps can and should change as the interests or the context of the project changes. That's fine! ### Who gets to put stuff on the roadmap? This is probably a larger governance question, so my thinking here is that we err on the side of merging ideas into the roadmap **unless** somebody raises a strong concern about an idea's inclusion on the roadmap. ### How many roadmaps would there be? I'm torn between thinking we should have one roadmap for the JupyterHub community (e.g. maybe in team-compass?) vs. different roadmaps for each of the major parts of the community. I'm leaning towards the latter, because different parts of the JupyterHub org require very different kinds of work, use-cases, timelines, etc. For example, I'd love to have a roadmap for team-compass specifically around increasing JupyterHub's contributor community. I'd also love a roadmap around improving "The Littlest JupyterHub" for educational purposes. ### Example roadmaps Here are a few example roadmaps from other projects, please feel free to add to the list: * [xarray](http://xarray.pydata.org/en/stable/roadmap.html) What do folks think about this? I'm just trying to start a conversation to see if people are OK with it, but please feel free to say "ahh this is too much structure and it'll probably never be updated" :-)
minrk commented 5 years ago

FWIW, we do have a roadmap and indeed, it never gets updated. I think it's a good goal to try to make it easier for interested folks to see a high level "where are they going", but I don't think we've found a good way to do it, yet. I guess adding "update/check-in with the roadmap" as a task in our monthly meetings might be a place to start.

choldgraf commented 5 years ago

My thinking is that if there's a per-repo roadmap, it might help the roadmap be more tightly-scoped around that repository, and more visible (both to users and to developers). Let's discuss the topic at our next team meeting?

betatim commented 5 years ago

I like having Now, Soon, Later as the three categories. My reading of them would be

I would be against using the ROADMAP as a place to collect feature requests. I'd still do this in issues or tell people that feature requests aren't a thing. What is a thing that the requestor starts work on the issue, maybe by starting a discussion to build consensus/is this useful.

Maybe we can adopt the idea I learnt from OKRs that the project has a ROADMAP that is more abstract/highlevel and the individual projects have their own maybe more detailed/concrete ones?

minrk commented 5 years ago

+1 to dev meeting. I think a roadmap (or more than one) is a good idea. It's mainly the question of making sure that we actually integrate its existence into our workflow that I don't have an answer to. We have demonstrated that "Yes, let's have a roadmap" is insufficient.

Per-repo might be too granular (I don't think oauthenticator or dockerspawner warrant one), but more than one makes sense (separate for jupyterhub, binderhub, z2jh? Maybe z2jh and kubespawner share one for "jupyterhub on kubernetes", though? Or maybe "kubernetes" should be a subsection under jupyterhub?)

choldgraf commented 5 years ago

I agree w/ both @betatim and @minrk. I'm thinking:

Now/soon/later but with a clear indication that this is all totally subject to change, it's more a way of signaling intent than signaling strict plans. In that sense, it's a way to signal feature requests that are "officially supported" but the JupyterHub team. Users in general shouldn't make PRs to that file, only contributors.

We choose a few "core" repositories to do this with (e.g. the "jupyterhub" repo could have a roadmap that encompasses several related repositories).

We add a list of all the roadmaps to the team compass page.

We make a note in team meetings to briefly cover each roadmap and ask for updates (this hopefully gives us some pressure to keep the roadmaps few in number :-) )

Maybe at the next team meeting we 1. Decide whether these roadmaps seem like a good system. 2. Decide on a few repositories to start with?

WDYT?

ellisonbg commented 5 years ago

I gave a talk about roadmaps at the NumFOCUS Summit that reflects on process of grant and White Paper writing that has happened this year. This does a good job of capturing my thoughts on certain aspects of roadmaps, so I am providing a link:

https://speakerdeck.com/ellisonbg/beyond-the-technical-roadmap-why-what-how-who

There are lots of aspects that I don't cover here though...

On Wed, Oct 24, 2018 at 9:04 AM Chris Holdgraf notifications@github.com wrote:

I agree w/ both @betatim https://github.com/betatim and @minrk https://github.com/minrk. I'm thinking:

Now/soon/later but with a clear indication that this is all totally subject to change, it's more a way of signaling intent than signaling strict plans. In that sense, it's a way to signal feature requests that are "officially supported" but the JupyterHub team. Users in general shouldn't make PRs to that file, only contributors.

We choose a few "core" repositories to do this with (e.g. the "jupyterhub" repo could have a roadmap that encompasses several related repositories).

We add a list of all the roadmaps to the team compass page.

We make a note in team meetings to briefly cover each roadmap and ask for updates (this hopefully gives us some pressure to keep the roadmaps few in number :-) )

Maybe at the next team meeting we 1. Decide whether these roadmaps seem like a good system. 2. Decide on a few repositories to start with?

WDYT?

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/jupyterhub/team-compass/issues/70#issuecomment-432719734, or mute the thread https://github.com/notifications/unsubscribe-auth/AABr0I5D8OR6j-yugJmYHHWeAWBfleWIks5uoI-ZgaJpZM4XxVug .

-- Brian E. Granger Associate Professor of Physics and Data Science Cal Poly State University, San Luis Obispo @ellisonbg on Twitter and GitHub bgranger@calpoly.edu and ellisonbg@gmail.com

choldgraf commented 5 years ago

A quick thought re: GitHub vs. non GitHub - I totally agree that we should also have this information on the documentation of each respective project (maybe by sym-linking a file and having it built with sphinx) as well as collected and displayed in the team-compass repository.

ellisonbg commented 5 years ago

Yeah, I think a hybrid approach like that would work well.

On Wed, Oct 24, 2018 at 12:45 PM Chris Holdgraf notifications@github.com wrote:

A quick thought re: GitHub vs. non GitHub - I totally agree that we should also have this information on the documentation of each respective project (maybe by sym-linking a file and having it built with sphinx) as well as collected and displayed in the team-compass repository.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/jupyterhub/team-compass/issues/70#issuecomment-432802132, or mute the thread https://github.com/notifications/unsubscribe-auth/AABr0JPx85afBvcTbuG8Rqs0oTPyY8Uqks5uoMNDgaJpZM4XxVug .

-- Brian E. Granger Associate Professor of Physics and Data Science Cal Poly State University, San Luis Obispo @ellisonbg on Twitter and GitHub bgranger@calpoly.edu and ellisonbg@gmail.com

choldgraf commented 5 years ago

A quick update on this, I had a comment from David Schaaf (works with Capital One and joined us at the NumFocus summit) regarding roadmaps in the Jupyter ecosystem. Wanted to share his thoughts with folks in case they're interested.

  1. I see no problem with maintaining separate roadmaps across the community as long as there is some mechanism to keep them aligned.
  2. Even with separate roadmaps, it may be a good idea to have a consolidated list of planned features, particularly for things the community it committed to.
  3. Instead of dates, I like @betatim's suggestion of now, soon, later to provide some minimal guidance.

and a question to consider:

  1. Does it make sense to leverage the roadmap repo(s) for feature suggestions and requests or do you feel like the current approach is better?
betatim commented 5 years ago

What is Capital One's use-case for roadmaps?

I'd be -1 on the roadmaps becoming a wish list or feature request lists. If there is a feature you would like to see and are willing to sponsor/implement/move forward then you can get involved via GitHub issues and PRs. Putting it on a list of feature requests makes it difficult to discuss so it seems more natural to create an issue for the discussion that is probably needed for anything but trivial features. Maybe we need a better way for people to post and take part in such discussions.

I am not sure I see the use case for "consolidated list of planned features, particularly for things the community it committed to", which to me reads like "we want feature X and you put it on your roadmap so now we will just wait for it to appear". In my experience there are a lot of things no one would oppose but also doesn't need badly enough that they'd work on it. So I am unclear on what the "community has committed to" means.

I think a better approach is "we'd like to see feature X, there are others who want something very similar, we are getting actively involved to build the compromise between their vision and ours."

choldgraf commented 5 years ago

re: use-case, I got the impression that a lot of it is trying to figure out what the general hopes are for the project. E.g., I've met several people at larger organizations who simply never thought JupyterHub was meant to be used for larger-scale deployments, and signaling from the community around "we'd love to have infrastructure to run things like Kubernetes" would have made them more likely to jump in and contribute rather than building their own stuff internally.

re: consolidated list, I got the feeling this was just a request to have a single place that aggregates the roadmaps of separate projects so that they're easier to discover.

Schaafd commented 5 years ago

@betatim This is David Schaaf. I think different organizations have different motivations. In the case of Capital One, I am more interested in seeing what is already being worked on that my team can contribute to, what is planned so if we do plan to work on something that could be useful to the community, we can ensure we are aligned with where the community is pushing JupyterHub, and, finally, what the general direction of the project looks like, so if we plan to use it for x, but the project is focused on y, we think of other options. Does that help?

betatim commented 5 years ago

Thanks a lot for the feedback and comments! I like what you said and it makes it more clear.

From an organisational point of view, could you default to posting an issue or getting involved in an existing one when you plan on building something? I think there are features that aren't controversial/complex -> high chances of being accepted and then there are others that need a bit of discussing and trading off of needs. This requires some discussion and input from people. For those it would be great to setup things so that organisations like yours could take part or start those discussions. I think that would be useful also for you because it would let you get involved with the planning and creation of the roadmap. Avoiding the "this does 80% of what we need but we still have to make our own" situation.

All this is motivated by my thinking that it is better to be involved in setting the direction of a project my business relies on than only observing/having to deal with decisions that I disagree with.

I've made good experiences with getting features added and bugs fixed via turning up and saying "We would like to achieve X. This is our suggestion for doing that, does that sound reasonable? If yes we will get building". Basically always the reaction has been positive and/or I got some free advice on how to improve it or save effort. For things that would be nice to have starting the discussion sometimes lead to someone else doing the work and sometimes it just sits there. What hasn't worked well is building something and then trying to contribute it when it was done. Similarly just because something was on a roadmap didn't mean it got done unless it was something someone was very keen on (or you paid them). (This is averaged over several open-source communities not just JupyterHub.)

I wonder how to scale that quite fluid/personal process up to bigger organisations.

minrk commented 5 years ago

I've met several people at larger organizations who simply never thought JupyterHub was meant to be used for larger-scale deployments

That may well be because for the first couple of years of JupyterHub, this was explicitly to be out-of-scope, and documented as such. It's entirely possible this is still mentioned in a few places. Large scale hubs is a big change to the roadmap for JupyterHub driven by demand, so this is probably the sort of thing that we would do well to communicate somewhere.

ellisonbg commented 5 years ago

I also think that major areas of work that either span multiple orgs/repos are in a different category.

Also there is a huge difference between a technical developer oriented roadmap, and one that is addressed to organizational decision makers.

Sent from my iPhone

On Nov 6, 2018, at 7:52 AM, Min RK notifications@github.com wrote:

I've met several people at larger organizations who simply never thought JupyterHub was meant to be used for larger-scale deployments

That may well be because for the first couple of years of JupyterHub, this was explicitly to be out-of-scope, and documented as such. It's entirely possible this is still mentioned in a few places. Large scale hubs is a big change to the roadmap for JupyterHub driven by demand, so this is probably the sort of thing that we would do well to communicate somewhere.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

Schaafd commented 5 years ago

@betatim That makes a lot of sense. I think that would be a great way to engage and aligns with what I have heard from other folks as well. I would be more than happy to encourage my team to start with filing an issue or looking for an existing one as a jumping off point for things they are working on. If that works, we can certainly take that route. With that said, from there, I do still think there is value to let those kind of discussions that grow into actual contributions translate into plans that show up on a roadmap in some way as a means to communicate such intent to the broader community. This is particularly important when that work will lead to underlying technical changes that may require users to make changes to how they interact with JupyterHub, perhaps bubbled up via a technical roadmap v one for decision makers (in reference to @ellisonbg comment above).

betatim commented 5 years ago

Can we collect some examples of good roadmaps in both categories? That might help people get started with creating something that others can recognise. There are worse ways to get started than copying the best :)

Side comment: if you have a moment for a quick read and feedback on the style, we are working on creating a technical roadmap for repo2docker here: https://github.com/jupyter/repo2docker/pull/465 the goal is to keep it very lightweight as there are very few permanently active contributors so the goal is more to give others an idea where things are going so that they feel like joining/when they make contributions they can see how it might fit (or not). All the while not spending a large amount of time doing planning things we can't promise to deliver because we rely on "drive by contributors" (it isn't as bad as it sounds, I promise :) )

jhamman commented 5 years ago

@choldgraf asked me to chime in here. I've seen roads be most effective when:

I think of roadmaps as long arc planning tools. The stuff you're working on now is obvious and probably will be out of date before the roadmap is published. I think you want to avoid updating the roadmap frequently.

One last comment, I think the road map is more useful to long-term developers than drive by contributors (like myself). It can be a helpful tool for explaining why something is in scope or not and a useful reminder of the long term development plan.

choldgraf commented 5 years ago

hey all - I updated the TLC with some information about where we are now re: roadmaps! please chime in here or in the linked issues if you have thoughts!

One question: does it make sense to have a TLJH roadmap as well? This project is a bit younger and still growing, so I was not sure whether it's something that's needed (in my mind, roadmaps are most useful once other organizations/people that aren't "core team" start depending on the tool more). @yuvipanda do you have thoughts on that?