Repository navigation
Link Contributor Guidelines broken #448
Description
Describe the bug
The link for the Contributor Guidelines in the README.rst is broken.
To Reproduce
Steps to reproduce the behavior:
- Go to README.rst
- Click on 'Contributor Guidelines' under the "Contributing" section.
- See error
Sorry. This page does not exist yet
Expected behavior
The link should lead you to our Contributing Guidelines in the stable documentation.
Desktop (please complete the following information):
- OS: macOS
- Version 11
Activity
rrjbca commentedon Mar 5, 2021
Before we make any changes can we discuss more generally wether we want to use hyperlinks to "stable" or "latest" documentation builds throughout the project? PR #416 is already open trying to change some links to "stable" while this issue is proposing the opposite. I think there is a fundamental question about wether the README and docs form part of a release, in which case they should surely use the appropriate "stable" links to remain self-consistent? And shouldn't we be thinking of the main branch as "unstable" and hence "latest" only exists for the benefit of developers working towards a new release?
Lucia-Fonseca commentedon Mar 5, 2021
Oh sorry I didn't see that. I was going through the list of issues and saw nothing.
Lucia-Fonseca commentedon Mar 5, 2021
However, despite the discussion whether we want to use "stable" or "latest", PR #449 is to fix that the link is broken. I am using the stable version as you propose in #416.
If you think this issue and #449 overlaps with #416, please feel free to close them.
ntessore commentedon Mar 5, 2021
README on main branch should link docs for main branch, i.e. latest. Docs for releases, e.g. on the PyPI page, should like to docs for that release, i.e. tagged.
We could easily write a script that automates packaging by patching the README before a release to PyPI. We could similarly add a
project_urls =entry to oursetup.cfgthat links the correct docs in the PyPI side bar.Edit: As we are passing into stable territory, we should in any case make the PyPI links for informative: Replace the broken
skypy.infolink for our homepage with a link to the docs, and add project_urls for repository, issues etc.rrjbca commentedon Mar 5, 2021
No, the link is currently dead because the page name has changed from upper to lower case since the last release and so the new name didn't exist at the time "stable" was last built. Without any change this will "fix-itself" with the next release. Your proposed change is simply linking to the old stable page and will break again after the next release as the upper case page name no longer exists on main.
rrjbca commentedon Mar 5, 2021
I would agree in principle, except most users treat repository READMEs on github like the "front page" for the project without appreciating that it could live on a branch that is under development. As such I'm really hesitant to put links to documentation for code that is unreleased and/or under development on the readme.
Yep this is a good idea to ensure that the releases are self-consistent
ntessore commentedon Mar 5, 2021
Do you have anything to indicate that the average user of Astropy or SciPy ever looks at astropy/astropy or scipy/scipy at all? I would think that once we have properly set up web and documentation pages, the only people making it to the repository will be people looking for the code. Everyone else will either follow the link on the arXiv page (-> website), google the name (-> website), or go through the PyPi page (-> website).
rrjbca commentedon Mar 5, 2021
You are right that probably most users don't ever visit the repo page, but clearly some do stumble upon it. I like the idea of separating the website for users and the repo for developers. That helps indicate what sort of information should be in the readme on main. The obvious requirement being that we need a website.