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.

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

Release: Fix changelog formatting #5529

Open
wants to merge 18 commits into
base: master
Choose a base branch
from
Open

Release: Fix changelog formatting #5529

wants to merge 18 commits into from
+261 −39

Conversation

snejus
Copy link
Member

@snejus snejus commented Dec 2, 2024 •
edited
Loading

Improve release notes formatting / changelog conversion from rst to md

During our last release, we discovered issues with changelog formatting. This PR improves and fixes several aspects:

Changes

  • Rewrite the changelog conversion logic to be more robust and maintainable
  • Fix indentation issues with nested bullet points
  • Improve handling of long section headers
  • Order bullet points alphabetically within sections for better readability
  • Use Sphinx objects.inv to resolve references and include links to the documentation in Markdown
  • Add tests to prevent formatting regressions
  • Add pandoc as a dependency for Ubuntu CI builds
  • Ensure documentation is built before generating changelog

@snejus snejus self-assigned this Dec 2, 2024
@snejus snejus requested review from bal-e and JOJ0 December 2, 2024 12:50
@github-actions GitHub Actions
Copy link

github-actions bot commented Dec 2, 2024 •
edited by snejus
Loading

Commit: ec78623

Changelog:

New features

  • Substitute Plugin: Allow the replacement string to use capture groups from the match. It is thus possible to create more general rules, applying to many different artists at once.

Bug fixes

Other changes

@snejus snejus force-pushed the fix-changelog-formatting branch 11 times, most recently from 6efe283 to 0bcb68c Compare December 4, 2024 09:16
@snejus snejus marked this pull request as ready for review December 4, 2024 22:59
@snejus snejus force-pushed the fix-changelog-formatting branch 3 times, most recently from 37cdfed to ec78623 Compare December 5, 2024 08:41
@snejus
Copy link
Member Author

snejus commented Dec 5, 2024

I converted part of the changelog (to stay under GitHub's max comment char limit) using this functionality, see how it's formatted:

Changelog

Changelog goes here! Please add your entry to the bottom of one of the lists below!

Unreleased

Other changes

2.2.0 (December 02, 2024)

New features

  • Substitute Plugin: Allow the replacement string to use capture groups from the match. It is thus possible to create more general rules, applying to many different artists at once.

Bug fixes

Other changes

2.1.0 (November 22, 2024)

New features

  • Ability to query albums with track db fields and vice-versa, for example beet list -a title:something or beet list artpath:cover. Consequently album queries involving path field have been sped up, like beet list -a path:/path/.
  • Beets now uses platformdirs to determine the default music directory. This location varies between systems -- for example, users can configure it on Unix systems via user-dirs.dirs(5).
  • New template function added: %capitalize. Converts the first letter of the text to uppercase and the rest to lowercase.
  • AutoBPM Plugin: Add new configuration option beat_track_kwargs which enables adjusting keyword arguments supplied to librosa's beat_track function call.
  • FtInTitle Plugin: New keep_in_artist option for the plugin, which allows keeping the "feat." part in the artist metadata while still changing the title.

Bug fixes

For packagers

  • The beet script has been removed from the repository.
  • The typing_extensions is required for Python 3.10 and below.
  • The minimum supported Python version is now 3.8.

Other changes

  • Added caching for dependency installation in all CI jobs which speeds them up a bit, especially the tests.
  • GitHub workflows have been reorganised for clarity: style, linting, type and docs checks now live in separate jobs and are named accordingly.
  • Installation instructions have been made consistent across plugins documentation. Users should simply install beets with an extra of the corresponding plugin name in order to install extra dependencies for that plugin.
  • The linting workflow has been made to run only when Python files or documentation is changed, and they only check the changed files. When dependencies are updated (poetry.lock), then the entire code base is checked.
  • The long-deprecated beets.util.confit module has been removed. This may cause extremely outdated external plugins to fail to load.
  • AutoBPM Plugin: Add plugin dependencies to pyproject.toml under the AutoBPM Plugin extra and update the plugin installation instructions in the docs. Since importing the bpm calculation functionality from librosa takes around 4 seconds, update the plugin to only do so when it actually needs to calculate the bpm. Previously this import was being done immediately, so every beet invocation was being delayed by a couple of seconds. 🐛 (Crash in autobpm plugin / Docs incomplete #5185)
  • Contributing: Since poetry now manages local virtual environments, tox has been replaced by a task runner poethepoet. This change affects beets developers and contributors. Please see updates in the Development Tools section for more details. Type poe while in the project directory to see the available commands.
  • Contributing: The project now uses poetry for packaging and dependency management. This change affects project management and mostly affects beets developers. Please see updates in Getting the Source and Testing for more information.

2.0.0 (May 30, 2024)

With this release, beets now requires Python 3.7 or later (it removes support for Python 3.6).

Major new features

New features

Bug fixes

For plugin developers

  • Allow reuse of some parts of beets' testing components. This may ease the work for externally developed plugins or related software (e.g. the beets plugin for Mopidy), if they need to create an in-memory instance of a beets music library for their tests.
  • beets now explicitly prevents multiple plugins to define replacement functions for the same field. When previously defining template_fields for the same field in two plugins, the last loaded plugin would silently overwrite the function defined by the other plugin. Now, beets will raise an exception when this happens. 🐛 (beetsplug: only one plugin can set template_fields per field #5002)

For packagers

Other changes

1.6.0 (November 27, 2021)

This release is our first experiment with time-based releases! We are aiming to publish a new release of beets every 3 months. We therefore have a healthy but not dizzyingly long list of new features and fixes.

With this release, beets now requires Python 3.6 or later (it removes support for Python 2.7, 3.4, and 3.5). There are also a few other dependency changes---if you're a maintainer of a beets package for a package manager, thank you for your ongoing efforts, and please see the list of notes below.

Major new features

Other new things

Bug fixes

For plugin developers

  • :pybeets.library.Item.destination now accepts a replacements argument to be used in favor of the default.
  • A new plugin event, album_removed, is called when an album is removed from the library (even when its file is not deleted from disk).
  • The pluginload event is now sent after plugin types and queries are available, not before.

Here are some notes for packagers

1.5.0 (August 19, 2021)

This long overdue release of beets includes far too many exciting and useful features than could ever be satisfactorily enumerated. As a technical detail, it also introduces two new external libraries: MediaFile and Confuse used to be part of beets but are now reusable dependencies---packagers, please take note. Finally, this is the last version of beets where we intend to support Python 2.x and 3.5; future releases will soon require Python 3.6.

One non-technical change is that we moved our official #beets home on IRC from freenode to Libera.Chat.

Major new features

Other new things

Fixes

For plugin developers

  • A revision attribute has been added to Database. It is increased on every transaction that mutates it. 🐛 (Add fallback for item access to album's attributes #2988)
  • Accessing fields on an Item now falls back to the album's attributes. So, for example, item.foo will first look for a field foo on item and, if it doesn't exist, next tries looking for a field named foo on the album that contains item. If you specifically want to access an item's attributes, use Item.get(key, with_album=False). 🐛 (Add fallback for item access to album's attributes #2988)
  • Similarly, we've replaced beets' configuration library (previously called Confit) with a standalone version called Confuse. Where you used to do from beets.util import confit, now just do import confuse. The code is almost identical apart from the name change. Again, we'll re-export at the old location (with a deprecation warning) for backwards compatibility, but we might stop doing this in a future release.
  • The beets.plugins.MetadataSourcePlugin base class has been added to simplify development of plugins which query album, track, and search APIs to provide metadata matches for the importer. Refer to the Spotify Plugin and the Deezer Plugin for examples of using this template class. 🐛 (Add Deezer plugin #3355)
  • The classes AlbumInfo and TrackInfo now convey arbitrary attributes instead of a fixed, built-in set of field names (which was important to address 🐛 (Extra fields from MusicBrainz (missing fields) #1547)). Thanks to @dosoe.
  • There were sporadic failures in test.test_player. Hopefully these are fixed. If they resurface, please reopen the relevant issue. 🐛 (Sporadic test failures in BPD tests #3309) 🐛 (fix "Sporadic test failures in BPD tests #3309" #3330)
  • Two new events, mb_album_extract and mb_track_extract, let plugins add new fields based on MusicBrainz data. Thanks to @dosoe.
  • MediaFile has been split into a standalone project. Where you used to do from beets import mediafile, now just do import mediafile. Beets re-exports MediaFile at the old location for backwards-compatibility, but a deprecation warning is raised if you do this since we might drop this wrapper in a future release.
  • Item.keys also has a with_album argument now, defaulting to True.
  • beets.util.command_output now returns a named tuple containing both the standard output and the standard error data instead of just stdout alone. Client code will need to access the stdout attribute on the return value. Thanks to @zsinskri. 🐛 (util.command_output: return stderr, too #3329)

For packagers

  • Beets' library for configuration has been split into a standalone project called Confuse, released as confuse. Beets now depends on this package. Confuse has existed separately for some time and is used by unrelated projects, but until now we've been bundling a copy within beets.
  • Beets' library for manipulating media file metadata has now been split to a standalone project called MediaFile, released as mediafile. Beets now depends on this new package. Beets now depends on Mutagen transitively through MediaFile rather than directly, except in the case of one of beets' plugins (in particular, the Scrub Plugin).
  • This version drops support for Python 3.4.

@snejus snejus requested a review from wisp3rwind December 28, 2024 07:23
@snejus
Add test for changelog formatting
ef4e983
@snejus
Remove poe output
aff43d8
@snejus
Unindent list items in the changelog
e9076ff 
I found out that GitHub Actions use pandoc version 2.9.2.1 which
converts bullet points like this:

echo '
* Item
* Another item
' | pandoc --from=rst --to=gfm
  - Item
  - Another item

Note that each item has two-space indent. Meanwhile, locally I've been
testing this conversion using pandoc 3.5 which does not add any indent:

echo '
* Item
* Another item
' | pandoc --from=rst --to=gfm
- Item
- Another item

This commit removes the indent and cleans up the how the replacements in
rst and md text are performed.
@snejus
Cache deps
914dbcb
@snejus
🤦
13e83cd
@snejus
Test rst to md conversion
7b9625b
@snejus
Fix ordering bullet point lists
d98226a
@snejus
Test nested bullet points conversion
dd96928
@snejus
Fix nested bullet points conversion
c26473e
@snejus snejus force-pushed the fix-changelog-formatting branch from ec78623 to eb557f7 Compare December 28, 2024 07:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@bal-e bal-e Awaiting requested review from bal-e

@JOJ0 JOJ0 Awaiting requested review from JOJ0

@wisp3rwind wisp3rwind Awaiting requested review from wisp3rwind

Assignees

@snejus snejus

Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
1 participant
@snejus