Skip to content

Deprecated author and author_email for authors according to PEP621 - #3131

Open
garvitshrma wants to merge 12 commits into
beeware:mainfrom
garvitshrma:authors-pep621
Open

garvitshrma wants to merge 12 commits into
beeware:mainfrom
garvitshrma:authors-pep621

Conversation

@garvitshrma

@garvitshrma garvitshrma commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

I have deprecated the author and author_email settings in favour of authors, following the PEP 621 configuration. A warning is now printed when a user uses the old settings (author and author_email). I have also added a note in the docs mentioning the deprecation of the two old settings. I have added authors as a list in every place. authors now contains both the author name and email.

Briefcase now follows the PEP 621 guidelines for the author settings.

Refs #1235

PR Checklist:

  • I will abide by the BeeWare Code of Conduct
  • I have read and have followed the CONTRIBUTING.md file
  • This PR was generated or assisted using an AI tool

Assisted-by: Claude Opus 5

@garvitshrma
garvitshrma marked this pull request as ready for review November 5, 2026 16:03

@freakboy3742 freakboy3742 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

This is a good starting point, and it looks like you've found most of the moving parts that are involved; however, it's not quite there yet.

The key detail that is missing: although we need to continue to accept author and author_email, as configuration values, the GlobalConfig and AppConfig should only be storing those values in the new "canonical" form - authors. There should be no references to author and author_email in the code, other than those necessary to process historical config files (and any time those historical settings are found, a warning should be raised).

Some of the logic that exists in parse_config is there to coerce a PEP 621 authors definition into Briefcase's definition; we need to reverse that, and coerce a historical Briefcase definition into PEP 621 form.

This may have some consequences outside the config files - for example, the create command references app.author and app.author_email when writing the app's dist_info. That reference needs to be updated to use the new app.authors. There's a couple of similar references in linux and windows packaging backends.

Comment thread docs/en/reference/configuration.md Resolved
Comment thread docs/en/reference/configuration.md Resolved
Comment thread src/briefcase/config.py Resolved
…ngs from docs, improved config.py to match the suggested improvement
@garvitshrma
garvitshrma marked this pull request as draft November 7, 2026 15:58

@freakboy3742 freakboy3742 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

This is definitely headed in the right direction; a couple of minor suggestions inline.

The approach you've taken in the create method looks about right to me. I'll admit I was a little surprised by the comma-concatenation, but I've confirmed that is what the dist-info file expects, so you've done the right thing there.

The test failures you're seeing at present have two causes:

  1. The configuration tests are currently configured to expect to see author and author_email in generated configurations, but with your changes, those keys are no longer generated. I flagged one of these in the review (the comment about updating the configuration to use the "current good" output); but there will be a couple of test configurations that currently define author and author_email that need to be updated to define authors instead.
  2. Coverage - you've added some new code paths that aren't tested. The coverage report is outputting:
Name                               Stmts   Miss Branch BrPart  Cover   Missing
------------------------------------------------------------------------------
src/briefcase/commands/create.py     425      6    106      4  97.4%   77-78, 83-84, 88, 90
------------------------------------------------------------------------------
TOTAL                               9335      6   2296      4  99.9%

So - in your code, Lines 77-78, 83-84, 88 and 90 of create.py aren't being executed by the test suite. Looking at the code, this suggests the tests that are exercising the write_dist_info method aren't passing in an authors configuration - so it's falling through to an empty list.

You'll likely also need to add some new test cases; at present, it's not possible to define an app that only has a name, or only has an email; so those branches won't be covered at present either.

The last piece that is missing is to update the references in the Linux and Windows backends to author and author_name. The Linux configurations will involve some research into how Linux system packaging tools (like RPM) express multiple authors; on Windows, there's a reference to app.author when running RCEdit. The fix there will likely be to just use the first author.

There's also the question of what happens when the user doesn't define authors, or defines an empty authors list. Strictly, PEP 621 doesn't require an author; we need to confirm if Linux and/or Windows has a problem if the author fields are omitted.

Comment thread src/briefcase/config.py Outdated
url: str | None
author: str | None
author_email: str | None
authors: list[dict] | None

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

We can go a little tighter with this type specification:

Suggested change
authors: list[dict] | None
authors: list[dict[str, str]] | None

Comment thread src/briefcase/config.py Resolved
Comment thread src/briefcase/config.py Outdated
Update your configuration to use `authors`:

authors = [
{name = "Jane Developer", email = "jane@example.com"},

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

We're in a position to provide the actual drop-in configuration here - we know what the actual name and email configuration should be, so the error message use that text directly.

Comment thread src/briefcase/config.py Outdated

# Must run before the PEP 621 merge, which removes the historical
# `author`/`author_email` settings once they have been coerced.
warn_deprecated_author_config(global_config, console)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Would it not make sense to keep all the deprecation code in one place? That way, when we finally finalise the deprecation, it should be a simple "delete this one function call" diff.

Comment on lines +41 to +43
"author": "First Last",
"author_email": "first@example.com",
"authors": None,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

In general, we try to keep our test cases "up to date" - that is, reflecting a "good", current configuration; and then make special cases of the configurations needed for testing historical/migration purposes.

Suggested change
"author": "First Last",
"author_email": "first@example.com",
"authors": None,
"authors": [{"name": "First Last", "email": "first@example.com"}],

@freakboy3742

Copy link
Copy Markdown
Member

One more thing to add to your testing regimen - we just received a PR that drew my attention to #2120. As part of this work, we'll need to remove the support for converting PEP 621 author names Briefcase-style author definitions in the convert command.

@garvitshrma
garvitshrma force-pushed the authors-pep621 branch 4 times, most recently from e1fab06 to 6a43a87 Compare November 13, 2026 21:36
@garvitshrma
garvitshrma marked this pull request as ready for review November 14, 2026 22:37
@garvitshrma

Copy link
Copy Markdown
Contributor Author

I have addressed all the review comments, and removed the PEP 621 author conversion from the convert command - it no longer builds a menu from [project] authors

@freakboy3742 freakboy3742 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

We're getting closer - this has some good progress, but there's still a few piece that need attention:

  • The logic for config parsing looks good now, except for one final piece of cleanup of logic from a previous pass.
  • The workflow on convert isn't quite right. It's asking the right questions if there's no author defined; but if I have a project that does have a well-formed PEP 621 authors field, there shouldn't be a need to ask for username and email at all, and there shouldn't be a need to repeat the author definition in the extra content added to pyproject.toml by the wizard.
  • As currently defined, this branch will always output author and author_email into the template context, which will then generate a new project in the "old" author format. We'll need to modify the template context used in the new and convert commands. There will be a related PR needed on beeware/briefcase-template to honor these new context values.
  • The special interpretation of "first author" in Debian, Arch and Windows packaging is worth a note in the Platform Quirks section of the respective platforms. On Windows, we should also note the interaction with use_full_install_path (and while we're at it, I notice that the docs for use_full_install_path aren't showing path separators for some reason...)

Comment thread src/briefcase/config.py Outdated
url: str | None = None,
author: str | None = None,
author_email: str | None = None,
authors: list[dict] | None = None,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Suggested change
authors: list[dict] | None = None,
authors: list[dict[str, str]] | None = None,

Comment thread changes/2120.bugfix.md Outdated

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

This isn't really noteworthy - it's not fixing a bug, it's a change in workflow brought about by the actual feature change. We don't need an extra changenote for that.

Comment thread src/briefcase/config.py Resolved
Comment thread src/briefcase/config.py Outdated
Comment on lines +1407 to +1408
The `author` and `author_email` settings are deprecated in favour of
`authors`.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Suggested change
The `author` and `author_email` settings are deprecated in favour of
`authors`.
The `author` and `author_email` settings have been deprecated in favour of
a PEP 621 formatted `authors` setting.

Comment thread src/briefcase/config.py Outdated
Comment on lines +1324 to +1327
# Coerce the historical `author`/`author_email` settings into the PEP 621
# `authors` representation.
author = global_config.pop("author", None)
author_email = global_config.pop("author_email", None)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

If the coercion has already occurred, this can't return anything other than None and None.

f"# Maintainer: {app.author} <{app.author_email}>",
f'export PACKAGER="{app.author} <{app.author_email}>"',
f"# Maintainer: {maintainer(app)}",
f'export PACKAGER="{maintainer(app)}"',

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

My read of the Arch packaging guidelines is that there can be multiple # Maintainer: lines, but only one PACKAGER.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

The refactoring here is good; but the naming of the methods isn't. It's easily to visually or syntactically) confuse maintainer() and maintainers(). Suggest renaming these primary_maintainer() and secondary_maintainers().

@garvitshrma
garvitshrma marked this pull request as ready for review November 19, 2026 22:34

@freakboy3742 freakboy3742 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

We're definitely getting closer; the core authors handling looks good now, we just need to finesse how the new and convert commands pass context to the template.

"""Initialize the extension with the given environment."""
super().__init__(environment)

def escape_toml(obj):

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

The location here is significant - it's a part of a Cookiecutter extension. We can't remove it from this location without breaking the ability of cookiecutter templates to render content as TOML.

f"# Maintainer: {app.author} <{app.author_email}>",
f'export PACKAGER="{app.author} <{app.author_email}>"',
f"# Maintainer: {maintainer(app)}",
f'export PACKAGER="{maintainer(app)}"',

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

The refactoring here is good; but the naming of the methods isn't. It's easily to visually or syntactically) confuse maintainer() and maintainers(). Suggest renaming these primary_maintainer() and secondary_maintainers().


If an application defines the use of an environment manager (using the [`env_manager`][] setting), and Docker is used to build the application, the environment manager will be ignored, and raw `pip` installs will be used.

### Only the first author is used as the package maintainer

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Suggested change
### Only the first author is used as the package maintainer
### Interpreting authors as package maintainers


For example, consider an installer that creates a `data` folder in the app, containing 2 files `a.dat` and `b.dat`. The MSI installer has a post-installation script that deletes `b.dat`, and adds `c.dat`. When the uninstallation process is executed, registry entries for `data/b.dat` and `data` will remain in the registry. A well-behaved app should *not* delete content that the MSI app installed; and it should not leave content in locations that would prevent the MSI from removing content that the MSI installed.

### Only the first author is used as the company name

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Suggested change
### Only the first author is used as the company name
### Interpreting authors as product owners

Comment on lines +350 to +352
An app can have more than one author. However, a Windows app has a single `CompanyName` property, so it uses the *first* author listed in the app's [`authors`][] setting.

If [`use_full_install_path`][] is turned on (which is the default), the app is installed into a folder named after `CompanyName`. This means that changing the order of the authors will also change where the app is installed.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Suggested change
An app can have more than one author. However, a Windows app has a single `CompanyName` property, so it uses the *first* author listed in the app's [`authors`][] setting.
If [`use_full_install_path`][] is turned on (which is the default), the app is installed into a folder named after `CompanyName`. This means that changing the order of the authors will also change where the app is installed.
An app can have more than one author. However, when [`use_full_install_path`][] is enabled (as it is by default), a Windows app is installed in folder matching the company that produced the app. Briefcase will use the name of the first author listed in the app's [`authors`][] setting as the company name.

Comment thread src/briefcase/commands/new.py Outdated
Comment on lines +470 to +471
"authors": authors_toml(authors),
"copyright_holder": copyright_holder(authors),

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

We shouldn't be passing rendered TOML to the template. We pass data to the template, and the template renders that data.

The new and convert commands now provide the app's authors as a pep621 context dictionary, leaving the template to render them. The toml_inline_table and lexical_join cookiecutter filters have been added so that a template can generate the TOML and copyright notice forms of that data.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants