Changelog updates

[choldgraf]

This adds a quarterly changelog for this year, starting January 1st. It uses a little github activity generator I wrote.

What do folks think about this? It's something we could semi-automatically update every 3 months and could be a way to make it easier for people to figure out what has changed.

Note: the changelog generator I linked to above uses GitHub tags for things - so I went through and tagged each of our closed PRs this year as "bug", "enhancement", "maintenance" or "documentation".

[choldgraf]

I'm not sure why our travis has become unhappy :-(

[betatim]

Restarted the builds.

Looks nice.

[betatim]

I would suggest we try and have three (or so) categories for PRs that we use across repo2docker and BinderHub. This way we might be able to use one script for both repos and not overload people with options so that they can tag PRs on creation.

In repo2docker we currently have https://github.com/jupyter/repo2docker/blob/master/docs/source/changelog.rst three categories in the change log: new feature, bug fix, API change. The latter doesn't get used a lot so maybe we can change it to a succinct version of "beware something has changed behaviour!'. For example switching from R 3.4 to 3.6 as the default. It is not a "breaking change" nor a "API change" but it is a big change.

I would not have a dedicated "documentation" label. Making changes to the docs is also either a new feature (new docs) or a bug fix (fixing mistakes).

I'd propose the following labels:

• "bug fix": fix something that used to be broken
• "new feature": add new functionality
• "change behaviour": changes the behaviour of something that existed already, moves something to a new home, stuff that isn't as it used to be and might trip up people.

I'd propose we use (nearly) the same visually quiet colour for all of these as it is mostly a bookkeeping tag.

WDYT?

---

As a point of order: can we please not perform large scale (re)tagging campaigns until after discussing them? It takes a bit of work to do the tagging and for it to be useful we need to all help apply these tags consistently. This means we need to create support amongst the devs first. If we do some tagging it costs time and nerves, then in the process of discussing it we change our mind (yay, retag it all, more time and nerves), and then maybe repeat this a few times. In the process of applying tags we make one of the most useful ways of finding issues/PRs useless. So I think this might be a case were waiting is better than the usual rule of "just do it".

If we do retag issues/PRs please start with the oldest PRs/issues not the newest.

For me "sort by most recently changed" is one of the best/only ways of finding things. Chances are stuff I am looking for is recent (close to the top) or I vaguely remember when we discussed it so I look in historical order but not by creation date. Unfortunately applying a tag bumps the "last activity date". If we had better full text search and the like this would be less of a problem but yeah, "sort by last activity" is (for me) the best (of all the suboptimal) ways of finding stuff.

[choldgraf]

Thanks for your feedback - I agree that it'd be helpful to standardize across the repositories. A few points below:

I'd propose the following labels:

Those sound fine to me, and in particular I like the API change tag. I personally find it useful to separate out things that changed in docs vs. in code, so I know how much each is getting attention, but if it'll keep things simpler I'm OK to not use a documentation tag. For changes that are under-the-hood but not bug-fixes, should we just not use a tag? (right now, I'm using "maintenance")

As a point of order: can we please not perform large scale (re)tagging campaigns until after discussing them?

Sorry about that - it didn't take me too long (maybe 15 minutes) and was strictly additive (I believe didn't "re-tag", only tagged for the first time) and only on closed prs so I didn't think it'd be an issue. I can see how this would make it frustrating if you're trying to find closed prs and sorting by "last updated", my apologies.

[betatim]

under the hood changes, small stuff

I think it is a good idea to have a tag for them even if they don't get explicitly listed in the Changelog. "maintenance" is ok but unspecific? Brainstorming: "keeping stuff ticking over", "kleinvieh" (only makes sense if you know the German saying "kleinvieh macht auch mist"), "everyday", "fundamental", "basics". Not a huge fan of any of these really but maybe they inspire someone.

No worries about the tagging. Used "retagging" as in "tagging after the fact" not as "changing existing tags". Either way I was grumpy because the search was frustrating me and then I resorted to looking by date and thought "heck, why all these old PRs first??? ahhrg ... ah someone actually put some effort into adding tags here! Wow!"

[choldgraf]

ok cool - how about we do:

For the changelog, I'll regenerate only including features + bugs. Are you ok with me re-taging the documentation PRs to make them "enhancement" or "bug"?

For API changes, I'll add support for that tag in github-activity, but I won't re-tag any issues on that one unless there are specific ones you know about

[betatim]

All sounds good!

[choldgraf]

OK, changelog updated, check it out here:

https://github.com/jupyterhub/binderhub/pull/975/files?short_path=8b1c3fd#diff-8b1c3fd0d4a6765c16dfd18509182f9d

WDYT?

[manics]

Is it easy to strip out the [MRG] part of the title?

[choldgraf]

That would be pretty easy to do if folks think it would improve the release notes. I could write a rule that's something like "if the PR name begins with [, then only keep everything to the right of the closing ]

[choldgraf]

ok changelog updated with title bracket tags stripped!

[betatim]

nit: the people who comment on PRs and issues are commenters or commentors? Can be changed in a new PR as well

When I read commentors I always hear co-mentors :D

Trying to understand why travis is unhappy.

[betatim]

The solution to travis was to restart it a bunch as there was noting obviously wrong with it :-/

Merging!

[betatim]

@choldgraf should we write down somewhere (in contributing.md??) how we determine what a "contributor" is?

Right now (from skimming your code) I think it is:

• author a PR
• comment on an existing issue

What do you think of changing "comment on an existing issue" to "comment on more than one issue not created by you"? The reason to raise the bar a bit is that we need to balance being inclusive (especially of none code contributions) but don't want to be too loose either because that makes it worthless to be listed as a contributor. My notion for inclusion would be "contributed effort" where "effort" is the thing it takes to push the project forward and is a scarce resource (mostly time spent with your brain engaged).