Skip to content

Fix API documentation links in README.md #490

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

Merged
merged 1 commit into from
Jul 3, 2025

Conversation

azarovalex
Copy link
Contributor

As of today the latest public release is 1.2.0 so API docs links in README.md are outdated, they still point to 1.1.0.
To avoid the maintenance cost of keeping URLs up to date this PR removes library version from URLs, making them always point to the latest stable release instead.

Another alternative would be to point URLs to the main branch (example), however for most of developers this README.md is the main entry point when installing the library and they would except to see docs for the latest stable release.

Checklist

  • I've read the Contribution Guidelines
  • My contributions are licensed under the Swift license.
  • I've followed the coding style of the rest of the project.
  • I've added tests covering all new code paths my change adds to the project (if appropriate).
  • I've added benchmarks covering new functionality (if appropriate).
  • I've verified that my change does not break any existing tests or introduce unexplained benchmark regressions.
  • I've updated the documentation if necessary.

@azarovalex azarovalex requested a review from lorentey as a code owner June 28, 2025 15:38
@lorentey
Copy link
Member

@swift-ci test

@lorentey
Copy link
Member

lorentey commented Jul 2, 2025

Note that the latest stable release is on the release/1.2 branch, not main.

@azarovalex
Copy link
Contributor Author

Note that the latest stable release is on the release/1.2 branch, not main.

Good point, however In this PR I propose for README.md on the main branch specifically to always point to the latest stable release, since this is the main readme that most users of this library see.

I opened this PR because I've been in this situation multiple times: I search online for swift-collections -> I land on Github with main branch open by default -> I click API docs link in README.md -> a webpage opens for an outdated release and I have to manually switch to the latest. I feel like it would be more convenient to always see the latest documentation.

Another alternative would be to keep every branch pointing to its own documentation (main points to main, release/1.2 to 1.2.x, etc.), but it would create additional maintenance cost to update these versions and it would send most people to main branch docs that is not what they usually want.

@lorentey
Copy link
Member

lorentey commented Jul 3, 2025

Yeah, I think this is fine. Landing this on release/1.2 would still make it appear on main (due to the (manual) propagation of changes from 1.2 → main), but this is not really worth arguing about. Thanks for catching this!

@lorentey lorentey merged commit c1b1ea9 into apple:main Jul 3, 2025
25 checks passed
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