Skip to content

Proposal: move release notes generation into docs repo - #1185

Open
jni wants to merge 15 commits into
napari:mainfrom
jni:relnotes-tools
Open

jni wants to merge 15 commits into
napari:mainfrom
jni:relnotes-tools

Conversation

@jni

@jni jni commented Oct 25, 2026

Copy link
Copy Markdown
Member

References and relevant issues

Relevant previous discussion is in Zulip.

Description

This PR proposes moving the release notes generation from a separate repo to
this one. The motivation is as follows:

  • When creating release notes, one has to maintain both a highlights section in
    napari/napari-release-tools and the full documentation update in this repo.
  • One then gets suggestions in the docs repo PR or subsequent PRs that then
    need to be backported to the additional notes in the docs repo.
  • Additionally, running the script is a bit cumbersome because one needs to
    specify the output directory, which is different for each release manager, so
    it can't be generalised in the script.

Moving the tooling and notes here makes it easier to keep everything in sync,
and also allows the script to have default values for the file paths, and it
then becomes easier to run with
uv run tools/generate_release_notes.py <milestone>
and no further arguments.

See the new README for more details.

  • Move generate release notes script to docs repo
  • Add additional needed files for release script
  • Improve spacing on docstring
  • Hard wrap lines for better printing on terminals
  • Remove the old script docstring from the module
  • raise -> raise from to please linter
  • Add README

@brisvag

brisvag commented Nov 11, 2026

Copy link
Copy Markdown
Contributor

I updated it with the latest release notes. Big +1 from me on this, it's a lot better like this than with 2 separate repo.

@brisvag
brisvag marked this pull request as ready for review November 11, 2026 14:09

@brisvag brisvag left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also fixed precommit and marked as ready for review. Would be great to get this in for the next release!

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

@brisvag brisvag left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Geting back to this, and I can't currently run it following the instructions... Working on it.

@Czaki Czaki left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't see a pyproject.toml, that is a source of dependencies.

Comment thread tools/env.yml

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know that this file was in original PR, but @DragaDoncila reported some problems with conda version of sqlite. Also, this file was not updated to be in sync with pyproject.toml. I suggest removing it.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It works really great for me... I think it is nice to provide a working environment for folks who prefer conda, in addition yes to a pyproject.toml and uv.lock. (But I agree that it is annoying that there's so many sources of dependencies...)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You run a generate release notes on current code with this env and it passes without disabling cache?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, it did on my Lenovo, which was using the conda env. Using UV and the single script (4884c8d), I seem to be getting a deadlock (I had to Ctrl-C after a long wait):

$ GH_TOKEN=(pbpaste) uv run relnotes.py 0.10.0
/home/jni/projects/napari-docs/tools/relnotes.py:107: DeprecationWarning: Argument login_or_token is deprecated, please use auth=github.Auth.Token(...) instead
  _thread_local.github = Github(GH_TOKEN)
Found 133 pull requests on query: milestone:0.10.0  for repo napari/napari
Pull Requests (napari/napari)...: 100%|████| 133/133 [00:04<00:00, 27.73it/s]
Found 39 pull requests on query: milestone:0.10.0  for repo napari/docs
Pull Requests (napari/docs)...: 100%|████████| 39/39 [00:02<00:00, 18.56it/s]
^CTraceback (most recent call last):
  File "/home/jni/projects/napari-docs/tools/relnotes.py", line 488, in <module>
    list(executor.map(lambda x: parse_pull(*x), pulls_to_parse))
    ~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/jni/.local/share/mamba/envs/all/lib/python3.14/concurrent/futures/_base.py", line 645, in result_iterator
    yield _result_or_cancel(fs.pop())
          ~~~~~~~~~~~~~~~~~^^^^^^^^^^
  File "/home/jni/.local/share/mamba/envs/all/lib/python3.14/concurrent/futures/_base.py", line 312, in _result_or_cancel
    return fut.result(timeout)
           ~~~~~~~~~~^^^^^^^^^
  File "/home/jni/.local/share/mamba/envs/all/lib/python3.14/concurrent/futures/_base.py", line 449, in result
    self._condition.wait(timeout)
    ~~~~~~~~~~~~~~~~~~~~^^^^^^^^^
  File "/home/jni/.local/share/mamba/envs/all/lib/python3.14/threading.py", line 369, in wait
    waiter.acquire()
    ~~~~~~~~~~~~~~^^
KeyboardInterrupt

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

... And with --no-cache I'm getting a weird encoding error... 🤦

Traceback (most recent call last):
  File "/home/jni/projects/napari-docs/tools/relnotes.py", line 358, in <module>
    repo = get_repo()
  File "/home/jni/projects/napari-docs/tools/relnotes.py", line 113, in get_repo
    return g.get_repo(f'{user}/{repo}')
           ~~~~~~~~~~^^^^^^^^^^^^^^^^^^
  File "/home/jni/.cache/uv/environments-v2/relnotes-f2f387d70681691f/lib/python3.14/site-packages/github/MainClass.py", line 518, in get_repo
    return github.Repository.Repository(self.__requester.withLazy(lazy), url=url)
           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/jni/.cache/uv/environments-v2/relnotes-f2f387d70681691f/lib/python3.14/site-packages/github/GithubObject.py", line 633, in __init__
    self.complete()
    ~~~~~~~~~~~~~^^
  File "/home/jni/.cache/uv/environments-v2/relnotes-f2f387d70681691f/lib/python3.14/site-packages/github/GithubObject.py", line 678, in complete
    self._completeIfNeeded()
    ~~~~~~~~~~~~~~~~~~~~~~^^
  File "/home/jni/.cache/uv/environments-v2/relnotes-f2f387d70681691f/lib/python3.14/site-packages/github/GithubObject.py", line 687, in _completeIfNeeded
    self._complete()
    ~~~~~~~~~~~~~~^^
  File "/home/jni/.cache/uv/environments-v2/relnotes-f2f387d70681691f/lib/python3.14/site-packages/github/GithubObject.py", line 692, in _complete
    headers, data = self._requester.requestJsonAndCheck(
                    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
        "GET", self._url.value, parameters=parameters, headers=self.__completeHeaders
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/home/jni/.cache/uv/environments-v2/relnotes-f2f387d70681691f/lib/python3.14/site-packages/github/Requester.py", line 659, in requestJsonAndCheck
    *self.requestJson(
     ~~~~~~~~~~~~~~~~^
        verb,
        ^^^^^
    ...<5 lines>...
        follow_302_redirect=follow_302_redirect,
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/home/jni/.cache/uv/environments-v2/relnotes-f2f387d70681691f/lib/python3.14/site-packages/github/Requester.py", line 1095, in requestJson
    status, responseHeaders, output = self.__requestEncode(
                                      ~~~~~~~~~~~~~~~~~~~~^
        cnx, verb, url, parameters, headers, input, encode, follow_302_redirect=follow_302_redirect
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/home/jni/.cache/uv/environments-v2/relnotes-f2f387d70681691f/lib/python3.14/site-packages/github/Requester.py", line 1236, in __requestEncode
    status, responseHeaders, output = self.__requestRaw(
                                      ~~~~~~~~~~~~~~~~~^
        cnx, verb, url, requestHeaders, encoded_input, stream=stream, follow_302_redirect=follow_302_redirect
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/home/jni/.cache/uv/environments-v2/relnotes-f2f387d70681691f/lib/python3.14/site-packages/github/Requester.py", line 1274, in __requestRaw
    response = cnx.getresponse()
  File "/home/jni/.cache/uv/environments-v2/relnotes-f2f387d70681691f/lib/python3.14/site-packages/github/Requester.py", line 207, in getresponse
    r = verb(
        url,
    ...<4 lines>...
        allow_redirects=False,
    )
  File "/home/jni/.cache/uv/environments-v2/relnotes-f2f387d70681691f/lib/python3.14/site-packages/requests/sessions.py", line 671, in get
    return self.request("GET", url, params=params, **kwargs)
           ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/jni/.cache/uv/environments-v2/relnotes-f2f387d70681691f/lib/python3.14/site-packages/requests/sessions.py", line 651, in request
    resp = self.send(prep, **send_kwargs)
  File "/home/jni/.cache/uv/environments-v2/relnotes-f2f387d70681691f/lib/python3.14/site-packages/requests/sessions.py", line 784, in send
    r = adapter.send(request, **kwargs)
  File "/home/jni/.cache/uv/environments-v2/relnotes-f2f387d70681691f/lib/python3.14/site-packages/requests/adapters.py", line 696, in send
    resp = conn.urlopen(
        method=request.method,
    ...<9 lines>...
        chunked=chunked,
    )
  File "/home/jni/.cache/uv/environments-v2/relnotes-f2f387d70681691f/lib/python3.14/site-packages/urllib3/connectionpool.py", line 793, in urlopen
    response = self._make_request(
        conn,
    ...<10 lines>...
        **response_kw,
    )
  File "/home/jni/.cache/uv/environments-v2/relnotes-f2f387d70681691f/lib/python3.14/site-packages/urllib3/connectionpool.py", line 499, in _make_request
    conn.request(
    ~~~~~~~~~~~~^
        method,
        ^^^^^^^
    ...<6 lines>...
        enforce_content_length=enforce_content_length,
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/home/jni/.cache/uv/environments-v2/relnotes-f2f387d70681691f/lib/python3.14/site-packages/urllib3/connection.py", line 566, in request
    self.putheader(header, value)
    ~~~~~~~~~~~~~~^^^^^^^^^^^^^^^
  File "/home/jni/.cache/uv/environments-v2/relnotes-f2f387d70681691f/lib/python3.14/site-packages/urllib3/connection.py", line 480, in putheader
    super().putheader(header, *values)
    ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^
  File "/home/jni/.local/share/mamba/envs/all/lib/python3.14/http/client.py", line 1359, in putheader
    values[i] = one_value.encode('latin-1')
                ~~~~~~~~~~~~~~~~^^^^^^^^^^^
UnicodeEncodeError: 'latin-1' codec can't encode characters in position 367-370: ordinal not in range(256)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is why I provided a lock file in the napari-release-tools repo.

Comment thread tools/__init__.py Outdated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a folder of scripts. I don't think the __init__.py should be there.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if I remember correctly Python was bugging me about importing from a sister .py file without it. But I might be mistaken.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It will be required only if you import from .file_name import something, not from file_name import something

Also, this will require using a tool by python -m tools.script not python path/to/script.py.

@jni

jni commented Nov 16, 2026

Copy link
Copy Markdown
Member Author

Ah, sorry I missed your review @brisvag! And good point @Czaki about the dependencies. 😅 I'll work on this tomorrow. @brisvag some more details about why you can't run it would be handy... 😅

@brisvag

brisvag commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

@jni

 uv run --locked generate_release_notes.py v0.10.0a
warning: `--locked` has no effect when used outside of a project
Traceback (most recent call last):
  File "/home/brisvag/git/napari-docs/tools/generate_release_notes.py", line 10, in <module>
    from packaging.version import parse as parse_version
ModuleNotFoundError: No module named 'packaging'

I think we need the pyproject as @Czaki says. I cannot run this at all at the moment... I think ideally this should just be a single uv script with its embedded dependency comment. I'm gonna work using the normal tools script for now, let me know if you solve this!

@Czaki

Czaki commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

I think ideally this should just be a single uv script with its embedded dependency comment

I added this as a project, to reduce the risk of release notes scripts stopping working in the middle of the release process. With pep-723 the uv might resolve again with a newer dependency version that might lead to a broken state.

Especially to avoid the situations like in #1185 (comment) where code execution hung while the version from napari-release-tools is still doing its job.

The code pattern used for speedup generation of notes is not the best one, and it looks like some of the updated dependencies is not thread safe.

Can we just limit this PR to copy stuff from napari-release-tools without any changes and do changes in follow-up PRs? This will simplify any debug task.

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

Labels

None yet

Projects

Status: No status

Development

Successfully merging this pull request may close these issues.

3 participants