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

Decide about a release-notes tool #3698

Closed
htgoebel opened this Issue Aug 27, 2018 · 6 comments

Comments

Projects
None yet
2 participants
@htgoebel
Member

htgoebel commented Aug 27, 2018

Opions

  • towncrier, see #2837
    • used by pip, Twisted, pytest
  • Docs say "news fragment types" can be configured, but don't say how. This example gives some insights.
  • Combined "news fragment types" seem to be not possible. My question in ununswered for a year now (see hawkowl/towncrier#90).
  • Seems to be not well maintained: docs are spare and inconsistent, even simple pull-requests are not merged for a year.
  • reno
    • used by openstack
    • According to Doug Hellmann's talk at EuroPython 2018 this is quite mighty and configurable to a large extend.
    • Release notes will be kept in a separate file per note and be combined when generating the documentation. Pro: Even the latest docs at rtd will be up-to-date. Con: These files need to be kept "forever". Con: Getting the changes from the last release without tool is hardly possible.
    • Unfortunately it does not work with our git-flow-based workflow, see https://docs.openstack.org/reno/latest/user/design.html#assumptions
  • blurb
    • used by CPython core development
    • Requires a tool for preparing an input-file which is then converted into the release entry.
@bjones1

This comment has been minimized.

Member

bjones1 commented Aug 31, 2018

Reno is my favorite, but is just fundamentally incompatible with our development process. blurb looks like a pain; it hides changes in randomly-generated files, which I don't like. That leaves towncrier. I like the way this is designed, but don't lack the very sparse docs.

@htgoebel

This comment has been minimized.

Member

htgoebel commented Sep 3, 2018

I managed to make towncrier work as I want it to. So towncier is the tool of choice.

@htgoebel htgoebel closed this Sep 3, 2018

@htgoebel htgoebel added this to the PyInstaller 3.4 milestone Sep 3, 2018

@htgoebel

This comment has been minimized.

Member

htgoebel commented Sep 6, 2018

@pyinstaller/contributors @pyinstaller/hook-maintainers

Since we are switching to towncrier for managing the changelog now, there is one important thing for you to keep in mind when committing or merging:
If a change is noteworthy, there has to be a newsfragment file for the changelog. Otherwise the change will not appear in the release notes/changelog.

Compiling the changelog manually was a huge effort, thus towncrier will speed up releasing a lot.
Due to towncrier I'll be able to release quicker (and hopefully do more often :-) But this also meant that I well send only a few minutes on the release-notes - just for sorting the entries a bit. If there is no newsfragment, the change will not be recorded - which is a bad thing if the change is user-visible.

You can find more details at https://pyinstaller.readthedocs.io/en/latest/development/changelog-entries.html (to be published later today). For sure we will need some time to get used to this, esp, on which "category" to use, when to use several entries or when to re-use/copy or maybe even change the newsfragment from anpother pull-request.

Noteworthy for those having commit-permissions: If you have neither a pull-request number nor a issue-number, use a unique alpha-numeric prefix (without dots!). This will make the fragment to show up in the changelog without a number.

Thanks for you supporting PyInstaller!

@bjones1

This comment has been minimized.

Member

bjones1 commented Sep 7, 2018

I'd like to fix a few things in the changelog generated by towncrier. Should I edit the individual news/ files, or edit the already-produced result in CHANGES.rst?

@htgoebel

This comment has been minimized.

Member

htgoebel commented Sep 8, 2018

As long as the changes have not been released, there are only the files in news/ (called newsfragments). Thus you should change there.
During the release process there is IMO no use in updating newsfragments, esp. since in most cases it's much easier to just change the changelog - which might need some revision after auto-generating it anyway.

Was this an actually or a theoretical question? I'd like to release 3.4 really soon now.

@bjones1

This comment has been minimized.

Member

bjones1 commented Sep 8, 2018

Go ahead and release -- I'll just fix up afterwards. Minor typos and formatting corrections.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment