Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Changelog updates #975

Open
wants to merge 2 commits into
base: master
from

Conversation

@choldgraf
Copy link
Member

commented Oct 9, 2019

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 choldgraf changed the title Changelog Changelog updates Oct 9, 2019
@choldgraf

This comment has been minimized.

Copy link
Member Author

commented Oct 9, 2019

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

@betatim

This comment has been minimized.

Copy link
Member

commented Oct 11, 2019

Restarted the builds.

Looks nice.

@betatim

This comment has been minimized.

Copy link
Member

commented Oct 13, 2019

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

This comment has been minimized.

Copy link
Member Author

commented Oct 13, 2019

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

This comment has been minimized.

Copy link
Member

commented Oct 13, 2019

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

This comment has been minimized.

Copy link
Member Author

commented Oct 13, 2019

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
2 participants
You can’t perform that action at this time.