Start capturing version information in a changelog

[sethmlarson]

Should we use towncrier? A simple changelog?

We should probably capture old changes in our changelog as well so that historical information isn't lost.

[lovelydinosaur]

Don't know what tooling if any we'd want, but certainly yup.
Personally I'm probably okay with us only starting to do so from some beta-release point onwards, but also happy if there's some good suggestions for us to just start with now.

[sethmlarson]

I've always wanted to use towncrier but it's a big burden to start using within a mature project. I can leave this open until you have more time to research the tool?

[lovelydinosaur]

I'm happy with the plain changelog that's been added.

I'd suggest that we don't bother with additional tooling around that, but we should make sure that we're being strict about making sure that https://github.com/encode/httpx/commits/master is a simple point of review for drawing up the changelogs, right?

I think it's probably better that we don't have pull requests themselves updating the changelog, but instead do that per-release, since it's otherwise a bit of a drag on contributors, and it's a really easy point to introduce noisy unneccessary conflicts.

Things that we'd need to make sure we're being clean about:

• Changes always come through as PRs.
• Pull request titles are always properly suitable for directly including in the changelog by the time they get merged.

Something I'm not so sure about is how we can best make sure that we're only including code changes in our CHANGELOG (ie. we don't really want to include docs pull requests or general project maintainence stuff in there, since it's a changelog for the packaged code, not the project as a whole.)

[sethmlarson]

Yeah I totally agree that creating a changelog is on the deployer. Much easier for contributors! :)

Let's only include stuff that matters for users. Docs, tests, cleaning up, etc don't matter to them.

[florimondmanca]

Agreed. I think changelog should only contain additions/changes/removals that impact the public API or anything users currently depend on. Also I like separating out changes into these categories (added, changes, deprecated, removed) so it’s easier to see what to pay attention to as a user — especially breaking changes.

As for updating the changelog, ideally this should always be done by the reviewer after every merge. This reduces the work needed before a deploy, and fits with the idea that master should always be in a releasable state.

[sethmlarson]

@florimondmanca So you're suggesting reviewers should be in charge of changelog entries being added within the scope of the PR that the feature is being added?

[florimondmanca]

@sethmlarson It depends on my understanding of within the scope of the PR. I do think it should be part of merging a PR to update the changelog accordingly if necessary. I don't know if the change should happen before or after the merge. My ideal setup would be to have a bot automatically adding the PR commit message to the changelog before/after the merge — don't know if there's anything like that out there though. :-)

(Of course, another option is to let the deployer update the changelog in a batch before a release as Tom suggested — I guess it depends on the preferred workflow.)

[sethmlarson]

This is done! :)

[lovelydinosaur]

I guess it depends on the preferred workflow.

A sensible thing to do would be to mandate that all changes come via a pull request.

That should include version bumps, which should include a changelog update.
I don't think we can entirely automate that, as it's still up for review. (Eg. ensuring descriptions are clean, ensuring that we only inclulde stuff that's a public facing issue, rather than eg. docs PRs)

[florimondmanca]

I think #291 was a good way to go in this regard. 👍