Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
Changelog updates #975
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".
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:
I'd propose we use (nearly) the same visually quiet colour for all of these as it is mostly a bookkeeping tag.
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.
Thanks for your feedback - I agree that it'd be helpful to standardize across the repositories. A few points below:
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")
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.
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!"
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