Skip to content

Fix API documentation links in README.md#490

Merged
lorentey merged 1 commit intoapple:mainfrom
azarovalex:fix-api-docs
Jul 3, 2025
Merged

Fix API documentation links in README.md#490
lorentey merged 1 commit intoapple:mainfrom
azarovalex:fix-api-docs

Conversation

@azarovalex
Copy link
Copy Markdown
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
Copy Markdown
Member

@swift-ci test

@lorentey
Copy link
Copy Markdown
Member

lorentey commented Jul 2, 2025

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

@azarovalex
Copy link
Copy Markdown
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
Copy Markdown
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
@lorentey lorentey added this to the 1.3.0 milestone Sep 27, 2025
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