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

Versioned GitHub repository links from our docs #6077

Open
emilk opened this issue Apr 23, 2024 · 2 comments
Open

Versioned GitHub repository links from our docs #6077

emilk opened this issue Apr 23, 2024 · 2 comments
Labels
📖 documentation Improvements or additions to documentation

Comments

@emilk
Copy link
Member

emilk commented Apr 23, 2024

We link to files on GitHub quite often in our docs.

For instance, we link to https://github.com/rerun-io/rerun/blob/main/examples/python/log_file/main.py
The problem is that that file is gone.
We should have linked to https://github.com/rerun-io/rerun/blob/0.15.0/examples/python/log_file/main.py instead

So how do we solve this?

Unclear

  • If we use /blob/main/ the file may change or disappear
  • If we use /blob/latest/ the file may also change or disappear, and the CI may be green just before a release, but the link in the release is wrong
  • If we hard-code tags in our links (/blob/0.15.0/) our docs will link to old code

Immediate problems for 0.16 release

(Fixed in #6331)

examples/cpp/external_data_loader/README.md
3:python: https://github.com/rerun-io/rerun/tree/latest/examples/python/external_data_loader/main.py

examples/rust/external_data_loader/README.md
3:python: https://github.com/rerun-io/rerun/tree/latest/examples/python/external_data_loader/main.py

examples/python/external_data_loader/README.md
3:python: https://github.com/rerun-io/rerun/tree/latest/examples/python/external_data_loader/main.py

docs/content/reference/sdk-operating-modes.md
93:Check out our [dedicated example](https://github.com/rerun-io/rerun/tree/latest/examples/python/stdio/main.py).

docs/content/getting-started/data-in/python.md
16:At any time, you can checkout the complete code listing for this tutorial [here](https://github.com/rerun-io/rerun/tree/latest/examples/python/dna/main.py) to better keep track of the overall picture.

Related

@emilk emilk added the 📖 documentation Improvements or additions to documentation label Apr 23, 2024
emilk added a commit that referenced this issue Apr 23, 2024
### What
While investigating recently broken links (because of
#5966 (comment)) I
decided to add a lint against linking to stuff on changing branches
(e.g. `/blobs/main`).

Unfortunately I cannot cover it all (see
#6077 for more), but this is an
OK start.

### Checklist
* [x] I have read and agree to [Contributor
Guide](https://github.com/rerun-io/rerun/blob/main/CONTRIBUTING.md) and
the [Code of
Conduct](https://github.com/rerun-io/rerun/blob/main/CODE_OF_CONDUCT.md)
* [x] I've included a screenshot or gif (if applicable)
* [x] I have tested the web demo (if applicable):
* Using examples from latest `main` build:
[rerun.io/viewer](https://rerun.io/viewer/pr/6078?manifest_url=https://app.rerun.io/version/main/examples_manifest.json)
* Using full set of examples from `nightly` build:
[rerun.io/viewer](https://rerun.io/viewer/pr/6078?manifest_url=https://app.rerun.io/version/nightly/examples_manifest.json)
* [x] The PR title and labels are set such as to maximize their
usefulness for the next release's CHANGELOG
* [x] If applicable, add a new check to the [release
checklist](https://github.com/rerun-io/rerun/blob/main/tests/python/release_checklist)!

- [PR Build Summary](https://build.rerun.io/pr/6078)
- [Recent benchmark results](https://build.rerun.io/graphs/crates.html)
- [Wasm size tracking](https://build.rerun.io/graphs/sizes.html)

To run all checks from `main`, comment on the PR with `@rerun-bot
full-check`.
@emilk emilk changed the title Linking to code from docs is dangeround Versioned GitHub repository links from our docs Apr 23, 2024
@jleibs
Copy link
Member

jleibs commented Apr 26, 2024

Just had a user run into errors when trying to run https://www.rerun.io/docs/howto/extend/extend-ui since they copied code from that link into their own project, and ended up using in-flux 0.16 APIs against the 0.15 release.

@emilk emilk added this to the 0.16 milestone May 3, 2024
@Wumpf
Copy link
Member

Wumpf commented May 15, 2024

Everything that is mentioned in an examples/ README.md should actually be trivial to solve: just do relative paths. landing has to understand that ofc then

emilk pushed a commit that referenced this issue May 15, 2024
### What

* Fixes problematic links mentioned in #6077
@Wumpf Wumpf removed this from the 0.16 milestone May 15, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
📖 documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

3 participants