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

Quarterly checkpoint for the Binder Project #216

Open choldgraf opened 4 years ago

choldgraf commented 4 years ago

In #213 we discussed the challenges around not having "releases" for BinderHub making it hard to give people checkpoints about what has changed / improved / etc.

@betatim had the idea that in lieu of releases, we release a quarterly "checkpoint" of activity for the project. This could let people know what we've been up to without requiring us to make an "official" release. This could also be a helpful way to zoom-out a bit and give a high-level view of what has happened.

What do people think about a blog post structure like this:

Binder team update: Q3 2019

< general description of major updates >

BinderHub updates

< general description of BinderHub updates w/ highlights >

< changelog-like list of closed PRs / issues / etc in time window (maybe w/ github-activity?) >

repo2docker updates

< general description of repo2docker updates w/ highlights >

< links to changelogs of releases since last update >

betatim commented 4 years ago

Is the headings/structure for us to help write it or part of the final blog post?

For the final post I'd try for one paragraph intro/teaser/hook, ~three paragraphs with highlights picked from any of the projects (We did X, Y and Z, together they form a nice story of letting you do more foo), then give an outlook (if possible) in one paragraph and then wrap it up.

Definitely no change log, bullet point list of all changes style :-/ We can probably make a GitHub link for a search that lists all closed PRs or links to an actual change log for those who want that kind of detail.

Otherwise I like the idea :) I think reusing structure and intro/outro from post to post is fine if not even a good idea. Radio, TV, streaming shows, etc each start the same way for each episode/broadcast. That gives structure/comfort to the consumer of it. You don't want novel structure each episode.

choldgraf commented 4 years ago

Why no changelogs? At least from the BinderHub repository's perspective, IMO this post basically is a changelog, since there's no other place for us to put that information. I suppose we could just have a date-based changelog in the BinderHub repo, and then link to that from a post like this?

betatim commented 4 years ago

I'll try and write a small example to try and illustrate what I mean.

Changelog style:

repo2docker

BinderHub

Story style:

Faster builds!

Building repositories is one of the things that takes a long time on mybinder.org. Over the last three months we have been working on changing that! This means that now your builds should be a lot faster than before. We improved the order of the build commands docker runs so that more of them are cached. This is particularly useful if you just fix a small typo in your README. This should be super fast now. Another big chunk of work was improving which node in a cluster a build is assigned to. Until now we assigned builds to nodes at random. This means that the chances of two builds of the same repository ending up on the same node were small. Which means all the cleverness of caching builds would not work as the caches aren't shared. We now assign the same repository to the same node to take advantage of the cache.

I find the story style more engaging and like it would tell the user what happened, why they should care and what is new/better. A short sentence in the change log, especially when spread over several repos means you need to read and realise that the combination of several of them means X for you. This is why I think picking three-ish highlights and writing a short paragraph for each from the user's perspective would be great. Then link to an extensive change log for those who are interested in the nitty gritty technical low level details.

choldgraf commented 4 years ago

I really like the story-like approach as well. Perhaps we do something like: story-style approach for this blog-like quarterly update, and on the BinderHub repository we just add a CHANGELOG.md file that is broken down by dates as opposed to by releases, with a note at the top of the file that explains this process. WDYT?

betatim commented 4 years ago

For the automated check point list creation script to work we need to tag PRs (and issues that result in a policy change or similar?). I expect the frequency with which we apply these tags "right then and there" will be proportional with how much mental overhead it is. So it would be good to use one set of tags for this across several repos instead of having subtly different tags, use a small set of tags and make the tag name descriptive to make it easy to pick one. I would prefer we start with a system that is (too) simple. Then in 6-9 months when we have been actively(!) using it and feel the pain we review the system and maybe introduce more fine grained labelling.

I made a proposal in https://github.com/jupyterhub/binderhub/pull/975#issuecomment-541399523. Getting feedback from the whole team would be great. I don't think we need to enforce usage or introduce it in every repo. That feels too heavy handed. However spending a little time to ponder and adjust now will save us a lot of pain in the future. I would like to adopt this system of tags and auto generation of the change logs in BinderHub and repo2docker. Maybe zero2jupyterhub is also interested? JupyterHub already has a system/process so maybe it is better to stick with that?