| RFC-0125: Shortlinks on Fuchsia.dev ||
|---|---|
| Status | Accepted |
| Areas | - Developer |
| Description | Allow redirecting fuchsia.dev/go/ to specific Fuchsia artifacts. |
| Gerrit change | - [553175](https://fuchsia-review.googlesource.com/c/fuchsia/+/553175) |
| Authors | - [nickvander@google.com](https://fuchsia-review.googlesource.com/q/owner:nickvander@google.com) - [curtisgalloway@google.com](https://fuchsia-review.googlesource.com/q/owner:curtisgalloway@google.com) |
| Reviewers | - [curtisgalloway@google.com](https://fuchsia-review.googlesource.com/q/owner:curtisgalloway@google.com) - [mkearney@google.com](https://fuchsia-review.googlesource.com/q/owner:mkearney@google.com) - [tkilbourn@google.com](https://fuchsia-review.googlesource.com/q/owner:tkilbourn@google.com) |
| Date submitted (year-month-day) | 2021-07-09 |
| Date reviewed (year-month-day) | 2021-09-01 |

[Edit this RFC](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/contribute/governance/rfcs/0125_shortlink_fuchsia_dev.md)
[Edit RFC metadata](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/contribute/governance/rfcs/_rfcs.yaml&searchAndJump=-+name:+'RFC-0125')

## Summary

Allow the use of shorter, meaningful, and durable links to specific Fuchsia
artifacts. These shortlinks ensure links won't degrade over time.

The proposed format is fuchsia.dev/go/ and would map to any fuchsia.dev document or a specific file in the Fuchsia source tree.

For example, fuchsia.dev/go/components could redirect to a page
such as fuchsia.dev/fuchsia-src/concepts/components/v2.

In most cases, these links should not be changed; however, there may be
exceptions, such as when the Component framework version change. The
go/link allows for a seamless transition between these version changes.

## Motivation

Shorter links are useful for things such as rubrics, specifications,
documentation, FAQs, supported hardware, and more. They are also helpful
with version updated, for example, Components v2.

This can also help with versioning of certain core parts of Fuchsia such
as Components.

## Stakeholders

Facilitator: hjfreyer.

Reviewers: mkearney, curtisgalloway.

Consulted: Members of FEC.

Socialization: RFC draft was shared with the technical writing team.

## Design

The design involves creating a directory in the source tree in `docs/go/`
to place a `_redirects.yaml` file.

This directory will include a `README.md` file to explain how to use the
redirects. It will also have an `OWNERS` file to review and approve the new
shortlinks. The `OWNERS` would also need to approve any possible changes to
existing `go` links. These changes should only be approved in very particular
cases, such as a replacement of a core concept, such as a new version of the
component framemwork.

The format of redirects would be in the following format:

    - from: /docs/go/<keyword>
      to: <path in source tree>

Example:

> [!NOTE]
> **Note:** This syntax can also point to source files outside of the `docs/` directory.

    - from: /docs/go/drivers
      to: /docs/reference/hardware/drivers.md

This redirect results in and points to .

## Implementation

Create three changes:

- A gerrit change that includes the new `docs/go` directory along with `_redirects.yaml`, `README.md`, and `OWNERS` files.
- A gerrit change that updates `doc_checker` for testing. See [Testing](https://fuchsia.dev/fuchsia-src/contribute/governance/rfcs/0125_shortlink_fuchsia_dev.md.txt#Testing).
- An overall redirect for fuchsia.dev to redirect fuchsia.dev/fuchsia-src/go/ to fuchsia.dev/go. fuchsia/src/go/ would be the path for `docs/go` on fuchsia.dev.

## Performance

> [!NOTE]
> **Note:** Only applies to fuchsia.dev.

This would result in a minor latency increase due to the redirect.

## Ergonomics

This enables contributors to make easy to remember keywords for Fuchsia
documentation.

## Backwards Compatibility

N/A.

## Security considerations

Technically, a `_redirects.yaml` file can be added in any of the
sub-directories of the `/docs/` directory to make redirects. However, the scope
of a `_redirects.yaml` file is limited to the directory in which the file
lives; there should not be an issue where other parts of fuchsia.dev get
redirected.

This proposal creates a `/docs/go/_redirects.yaml` file which limits the
redirect scope to only fuchsia.dev/go/. In the background, a higher-level
redirect takes care of redirecting fuchsia.dev/fuchsia-src/go to
fuchsia.dev/go. Keep in mind that once the git repo is moved into fuchsia.dev,
the `fuchsia-src/` directory is mapped to the `docs/` directory.

## Privacy considerations

N/A.

## Testing

[`doc_checker`](https://cs.opensource.google/fuchsia/fuchsia/+/main:tools/doc_checker/)
can be expanded to verify that:

- The `- from:` fields only have `/docs/go` paths to avoid issues.
- The `to:` links exist.
- The other .md files in `/docs/` are not referencing broken `/docs/go/` links.
- Problematic words or phrases are not used in the names of links.
- No duplicate `go` keywords exist.

## Documentation

Create a `README.md` that explains the syntax for the file along with the
following items:

- Rubric for making a shortlink. See [rubric](https://fuchsia.dev/fuchsia-src/contribute/governance/rfcs/0125_shortlink_fuchsia_dev.md.txt#rubric) For example, things that should have a permanent reference in case of a reorganization. Any reviewer could consult this rubric to determine the validity of proposed links.

### Rubric

Short links (fuchsia.dev/go) are intended to be durable, have a meaningful
name, and be of general interest. The links are durable and use a
flat namespace, so it is desirable to carefully consider each proposal
to limit the number of created short links.

Reviewers should consider the following factors to approve pending short
link requests:

- Will the proposed link be relevant for a long time?
  Links are intended to be durable, so you should be reasonably confident
  that a link will continue to be of general interest for a long time.

  - Positive example:
    A general Fuchsia FAQ page or the current list of supported hardware. Even
    though they will change over time, the topics will be relevant
    indefinitely.

  - Negative example:
    An RFC proposal that is under consideration. While the proposal is
    currently relevant, it will be either accepted or rejected. If accepted,
    it may be a suitable short link topic for reference.

- Does the link cover a general topic or concept? Is it relevant for a wide
  audience?

  - Positive example:

    - An overview of FIDL. This is a fundamental technology used by Fuchsia.
    - The Fuchsia security model. This is of interest to both users and developers.
  - Negative example:

    - Documentation for a single system call. A link to the list of system calls would be more relevant.
    - Instructions for booting a specific model of NUC over Ethernet. A link to a more general page on booting Fuchsia on categories of devices would be of interest to a wider audience.
- Does the link duplicate an existing easy-to-use link that is unlikely to
  change?

  - Positive example: is unlikely to change, so is probably redundant.
- Is the link name meaningful, and does it comply with the
  [Respectful Code policy](https://fuchsia.dev/docs/contribute/respectful_code)?
  Short links should be, of course, short, but not at the expense of being
  understood.

  - Positive example:
    Both of these examples are short and descriptive:

    - `/docs/go/faq` (renders as fuchsia.dev/go/faq).
    - `/docs/go/hardware-specs` (renders as fuchsia.dev/go/hardware-specs).
- Does the `to` link point to a document inside of the `/docs/` directory?

  - Positive example:

    - `to: /docs/concepts/software_model.md`.
  - Negative example:

    - `to: http://google.com/`.

## Drawbacks, alternatives, and unknowns

N/A

## Prior art and references

Examples from link shortners such as:

- <http://bit.ly/>

[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/contribute/governance/rfcs/0125_shortlink_fuchsia_dev.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/contribute/governance/rfcs/0125_shortlink_fuchsia_dev.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/contribute/governance/rfcs/0125_shortlink_fuchsia_dev.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/contribute/governance/rfcs/0125_shortlink_fuchsia_dev.md "Edit the source code of this page")