Establish and use a single pattern for source code references.

[aiuto]

Description of the problem / feature request:

Our code and docs contain pointers to our code. For consistency, we should use a single format, but do not. For example, aquery.html uses 3 different formats.

href="/bazelbuild/bazel/tree/master/tools/aquery_differ
href="https://source.bazel.build/bazel/+/master:src/main/java/com/google/devtools/build/lib/actions/Actions.java;l=59;drc=146d51aa1ec9dcb721a7483479ef0b1ac21d39f1
href="https://cs.opensource.google/bazel/bazel/+/master:src/main/java/com/google/devtools/build/lib/actions/ActionAnalysisMetadata.java;l=89;drc=8b856f5484f0117b2aebc302f849c2a15f273310

Further compounding the problem is that many links are incorrect, because they refer to a line number, but not at any fixed revision.

Possible Requirements

• Should we standardize on one repository to point to?
  • Of course yes.
  • Which one?
    • github is obviously correct because that is where the code is hosted
    • opensource.google.com has better functionality.
• What is the meaning of a permalink to a line of code?
  • should we allow that in user documentation or only within code?
    • My vote would be only within code. End user docs should not require Bazel source to understand. (@floriographygoth - thoughts?)
  • even within code, is a permalink useful when it can go stale?
    • should we use query patterns rather than line numbers?
  • should permalinks point to the default branch (master, but soon to be main) or to HEAD?
    • pointing to the branch allows the link to stay within the branch when we do development in LTS branches.
      • but when you write the code in main and then you are browsing on an LTS branch, you get sent to the main branch rather than the branch you work in. So that is a fail
    • if we point to HEAD, then do you get the most recent commit on the branch you are viewing for?
      • that seems right.
      • I do not know if it works
• How does this play with examples and LTS?
  • Versioned documentation may want to point to an examples repository (code, but not bazelbuild/bazel code) with URLS.
  • So we have similar questions.
  • I believe if is generally sufficient to only do references of the form "See the frobnitz example" where we have a link to https://github.com/bazelbuild/examples/blob//...
  • That is. Always be careful to use the branch name because we need an examples branch to go with each LTS branch, and do not point to much at individual lines. The examples should only do that within themselves.

Proposal

• Answer the questions above
• Publish the rules in the overall contribution/coding standards guide
• Align the world

As a first step, my presumption is

• Point to github.com
• Remove references to code in end user documentation
• In technical docs for how to work on Bazel we should point to files only
  • syntax: ... See the frobnitz function in <link to file at HEAD> (or to main if we make that choice)
• Within code
  • Favor query for functions rather than links to lines
  • If you MUST point to a specific version or line. Use the github commit in the URL

[aiuto]

I placed this in team-documentation for now because I would like some input about my proposed prohibition against end-user docs pointing into source code.
After that, it might shift to EngProd, or general product.

[oquenchil]

I placed this in team-documentation for now because I would like some input about my proposed prohibition against end-user docs pointing into source code.
After that, it might shift to EngProd, or general product.

Tony, can you assign a priority to this?

[aiuto]

Sure. I made it P2 because nothing is truly broken right now.
That said, I think the first part - establishing the pattern - should be a P1 where @floriographygoth gets a lot of say in the requirements and style. After that, updating all the existing links is more of a P3.

[floriographygoth]

I agree with your proposal.

• Github links @ HEAD seem like the way to go.
• No line numbers, if truly necessary, reference the commit
• Minimize linking to code from docs, where possible
• Re: versioned examples, let's have a chat

How should we proceed?

[aiuto]

For the first three points, we just declare it so. When I do the draft update of the coding standards I'll incorporate those guidelines. Someone can clean up most of the older broken links when they want to tidy up instead of work on new things (since that part is P3).

For the versioned examples, we can chat more. That is going to require some thinking.