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.

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

Add more project urls to setup.cfg #53

Closed
wants to merge 1 commit into from

Conversation

septatrix
Copy link

The set of urls which have special handling on pypi can be found in the warehouse repo:
https://github.com/pypa/warehouse/blob/main/warehouse/templates/packaging/detail.html#L20-L60

Fixes #52.

The set of urls which have special handling on pypi can be found in the warehouse repo:
https://github.com/pypa/warehouse/blob/main/warehouse/templates/packaging/detail.html#L20-L60
Comment on lines +8 to +12
project_urls =
Documentation = https://blog.jaraco.com/a-project-skeleton-for-python-projects/
Source Code = https://github.com/jaraco/skeleton
Issue Tracker = https://github.com/jaraco/skeleton/issues
Changes = https://github.com/jaraco/skeleton/blob/main/CHANGES.rst
Copy link
Owner

Choose a reason for hiding this comment

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

Each one of these project URLs adds another bit of toil for the project. Each project that inherits from skeleton is going to need to update these URLs and in some cases replace them (if RTD is used, the changes are published in RTD with more fidelity). In the case of Documentation, the URL will need to be removed or replaced entirely. Especially with "Source Code" and "Issue Tracker", these URLs are barely more valuable than the url of the project, so it's definitely not worth the trouble of substituting these throughout.

In other words, this one change here implies hundreds of changes downstream.

In #52 (comment), I propose a different approach, which will re-use the RTD link in the README as the source of truth for documentation and derive the URLs from that signal.

Assuming that approach is possible, it will alleviate all of the toil of customizing these URLs and supplying them separately for hundreds of projects, and it will also avoid situation where some URLs are updated but not others. I'd like to explore that approach first.

Copy link
Author

Choose a reason for hiding this comment

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

Each one of these project URLs adds another bit of toil for the project. Each project that inherits from skeleton is going to need to update these URLs and in some cases replace them

How is this different from all the other metadata fields? name, author, author_email, description, url and classifiers all have to be updated anyhow.

In the case of Documentation, the URL will need to be removed or replaced entirely.

Yes. However updating or removing a URL is easier than adding it if you do not even know that this URL is shown on PyPi amongst other places.

Especially with "Source Code" and "Issue Tracker", these URLs are barely more valuable than the url of the project, so it's definitely not worth the trouble of substituting these throughout.

Simply changing the project reference in the URLs takes only a couple seconds. Furthermore for projects which have do not have everything on GitHub these URLs can be rather valuable. Flask for example does link to their github page in the url/homepage section. Django does not use github issues but have their own bug tracker instead. Also monorepos can directly link to the proper subdirectory in the repository.
I firmly believe these are vital features and should not be disregarded. For those who do not want these additional urls they are free to simply remove them which only takes a few seconds though for those who benefit from them it is important to know of their existence and using them will make the lives of everybody a bit nicer.

In #52 (comment), I propose a different approach, which will re-use the RTD link in the README as the source of truth for documentation and derive the URLs from that signal.

Not everyone will benefit from that approach as not everyone uses RTD. Also not everyone might link to their documentation in the README but e.g. instead use the github sidebar etc. Additionally this only seems to apply to the documentation url and nothing else: source code, issue tracker and changelog would still be left out.

Also after looking at the setuptools issue you linked it seems to me that his steps would already be finished after number 4 if a changelog url were added to the metadata as this would then show up in pypi. Regarding the added link in the github releases I have no strong opinion. Personally I would prefer the changelog to be directly embedded because then I could also directly see the changes from old releases but that is an improvement in another place orthogonal to the one proposed here.

Copy link
Owner

Choose a reason for hiding this comment

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

How is this different from all the other metadata fields? name, author, author_email, description, url and classifiers all have to be updated anyhow.

  1. Most of these fields are not redundant or derivable from other fields. Moreover, they've already been defined for existing packages. classifiers in particular are configured for reasonable defaults, so don't necessarily require customization.
  2. I'm not happy that these fields have to be supplied either. I'm working on some efforts in the Setuptools project to derive reasonable default values for these fields from repository metadata or a source of truth.
  3. I'd like to minimize the number of tweaks that one needs to make to publish a package.

For those who do not want these additional urls they are free to simply remove them which only takes a few seconds though for those who benefit from them it is important to know of their existence and using them will make the lives of everybody a bit nicer.

The purpose of this repo is not to provide a general-purpose demonstration of a package, but to provide a re-usable pattern for actual packages and specifically for projects that I maintain or that others maintain following this pattern. A better place to learn about the available options would be the packaging guide. Until these metadata have value for the projects this skeleton supports, it only serves as a distraction and toil to add them. For example, to add them here would require removing them across hundreds of dependent repos. Would you be willing to do all of that work? I know I'm strongly reluctant.

Not everyone will benefit from that approach as not everyone uses RTD. Also not everyone might link to their documentation in the README but e.g. instead use the github sidebar etc. Additionally this only seems to apply to the documentation url and nothing else: source code, issue tracker and changelog would still be left out.

Sure, and that means this repo then becomes more toilsome for its primary user (me) in order potentially be more usable for others.

I want to avoid adding complexity and toil to this repo. Instead, I'd like to see automated solutions that can generate or infer or otherwise centrally manage the pattern of adding these different project URLs to a project's metadata. Perhaps through a setuptools plugin that detects that it's Github and generates the relevant derived URLs.

Thanks for your thoughtful consideration on this matter, but I consider it closed for now. I'd welcome other proposals that are less invasive to the workflow of the users of the repo.

Copy link
Author

@septatrix septatrix Apr 22, 2022

Choose a reason for hiding this comment

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

How about leaving them in but commented? One motive for this PR was that I feel like few people know about these fields even though they are very useful. Having them as comments does not require any additional tweaks before publishing but still educated users about their existence.

And yes, hinting at them in packaging guides would be desirable however from my own and colleagues experience these are only skimmed for the most important things and afterwards only visited on in an as-necessary fashion

@jaraco jaraco closed this Apr 22, 2022
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.

Link to documentation
2 participants