Skip to content

Use Towncrier for Changelog? #270

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.

Sign up for GitHub

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

Jump to bottom
Closed
tomschr opened this issue Jun 15, 2020 · 6 comments
Closed

Use Towncrier for Changelog? #270

tomschr opened this issue Jun 15, 2020 · 6 comments
Labels
Infra All about infrastructure (GitHub Action, project build etc.) Question Unclear or open issue subject for debate

Comments

@tomschr
Copy link
Member

tomschr commented Jun 15, 2020

Situation

Currently, all changes are recorded in a single CHANGELOG.rst file. In most cases this is enough and it works well.

However, in some cases conflicts can occur. Sometimes it would be helpful to have a tool which could create that changelog automatically.

Idea

Some projects use the towncrier tool. It is built around "news fragments", little text snippets that are stored in different files under a common directory (e.g. changes.d). When a new release is drafted, these files are brought together and create the final changelog file. This minimizes any conflicts.

Every filename contains an issue number and a "type". A type can be feature, bugfix, doc, removal, or you can use self-defined types. These types will become sections in the final changelog file. All fragments are collected, sorted, and added under the sections.

When Towncrier is correctly set up, a typical workflow looks like this:

  1. Start working on a specific issue, let's say, 123.
  2. Decide what type this issue is, for example, feature, bugfix, etc.
  3. Combine the two information and create a fragment file: towncrier create 123.bugfix.
    This file will be added inside the changes.d directory.
  4. Describe the issue.
  5. Commit the file.
  6. Merge issue to master.

The more issues you solve, the more files you will collect inside your changes.d directory. At some point, we need to create a new release. In this case, the workflow looks like this:

  1. Create a new release branch.
    (could be done in other ways too, but this makes things a bit easier).
  2. Raise the version.
  3. Produce a draft changelog to see everything is included with: towncrier build --draft.
  4. If satisfied, produce the final changelog file with: towncrier build.
    This command will remove all files inside the changes.d directory and create the final changelog file.
  5. Commit all changes and merge it.

Pros

  • All changes reside in single files under a common directory, for example, changes.d.
    This makes it easier to see which will end up in the new release.
  • Reduces conflicts as changes are stored in separate files.
  • Able to configure

Cons

  • Works on Python 3.5+ only.
    (This may be not as a big disadvantage as we move to Python 3 soon.)
  • Every file has to be named with ISSUE-TYPE. This may not always appropriate.
  • Towncrier works best in a development system where all merges involve closing a ticket.

@python-semver/reviewers @tlaferriere what do you think about that? Would that be helpful or just too much?
@tomschr tomschr added Infra All about infrastructure (GitHub Action, project build etc.) Question Unclear or open issue subject for debate labels Jun 15, 2020
@tlaferriere
Copy link
Contributor

Works on Python 3.5+ only.

Even with our 2.x I don't think this is an issue since this is a dev tool. No need to require the end users to have py >=3.5.

I see there are quite a few steps to this workflow, which will increase the chance to forget something. I think this would be best if it could be integrated with tox and easily automated.

@tomschr
Copy link
Member Author

tomschr commented Jun 15, 2020

Thanks Thomas for your feedback! 👍

Works on Python 3.5+ only.

Even with our 2.x I don't think this is an issue since this is a dev tool. No need to require the end users to have py >=3.5.

Yes, I think, the normal user shouldn't be affected much as the releases are done by the maintainers only.

I see there are quite a few steps to this workflow, which will increase the chance to forget something. I think this would be best if it could be integrated with tox and easily automated.

I thought of that too. 😉

Maybe my description was a bit verbose, but I wanted to make sure it contains some "flesh".

Typically, the normal user has to create only one file with a specific name and some content. That's all. I think, this is not really difficult. We could describe that in our "Contributing" section.

For the release manager(s), there are indeed some more steps involved. As you rightfully noted, this can be done with tox.

@tlaferriere
Copy link
Contributor

Every file has to be named with ISSUE-TYPE. This may not always appropriate.

Looking at the pypi page, the possible issue types seem to be rather complete, even including a misc type that can be good catch-all for all infra related stuff.

Towncrier works best in a development system where all merges involve closing a ticket.

We can ask the people who open PRs to also open an issue for reference and discussion.

In the end, I'm always for more automation, as it allows us to focus more on the essentials, and removes possibility for mistakes. That's a yes from me 👍

@tomschr
Copy link
Member Author

tomschr commented Jun 16, 2020 •
edited
Loading

Looking at the pypi page, the possible issue types seem to be rather complete, even including a misc type that can be good catch-all for all infra related stuff.

That's true. I also worked with Towncrier in a local branch. The only issue that I found is, when you do not have an issue, but you want to record the change.

We can ask the people who open PRs to also open an issue for reference and discussion.

You mean, we should separate the issue from a new issue which is only related to the fragment? Or maybe I missed your idea.

In the end, I'm always for more automation, as it allows us to focus more on the essentials, and removes possibility for mistakes. That's a yes from me 👍

Thanks. 😃 Yes, automation is usually a good thing. Just wanted to make sure I don't over-engineering it. 😉

I still have my local branch. If I push it we can play with that.

@tomschr tomschr mentioned this issue Jun 16, 2020
Closed
@tlaferriere
Copy link
Contributor

The only issue that I found is, when you do not have an issue, but you want to record the change.

If that change is worth recording, maybe it is also worth creating an issue for 😉.

You mean, we should separate the issue from a new issue which is only related to the fragment?

I meant that each pull request (change effected) should close at least one issue.
For example, take the first PR I did on this repo: I just coded the changes, didn't bother actually creating an issue to discuss goals beforehand. In this case, if we were using towncrier, a part of getting this PR accepted would have been to open an issue and link it in towncrier and in the PR.
As for splitting off issues from another issue, I think this has more to do with what we consider to be in the scope of said issue (see the first sentence of this comment).

I think that having an issue for each changelog entry would make us more aware of what is actually changing, and it would encourage discussion on changes that could actually affect the users.

While we're at it, I have to say that I like the projects feature for repos and I think we should use it more (e.g for feature releases). I think it's a nice visual for tracking progress on related topics.

@tomschr
Copy link
Member Author

tomschr commented Oct 26, 2020

I think, that is closed with #290 and commit cbd4335

@tomschr tomschr closed this as completed Oct 26, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Infra All about infrastructure (GitHub Action, project build etc.) Question Unclear or open issue subject for debate
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Configure and add Towncrier files tomschr/python-semver
2 participants
@tomschr @tlaferriere