Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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
andclassifiers
all have to be updated anyhow.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.
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.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
classifiers
in particular are configured for reasonable defaults, so don't necessarily require customization.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.
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.
There was a problem hiding this comment.
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