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

x/pkgsite: automatically link RFCs in package documentation #38056

audiolion opened this issue Mar 25, 2020 · 4 comments

x/pkgsite: automatically link RFCs in package documentation #38056

audiolion opened this issue Mar 25, 2020 · 4 comments


Copy link

@audiolion audiolion commented Mar 25, 2020

What is the URL of the page with the issue?

Compared to: would automatically link to RFCs

What did you expect to see?

RFCs automatically linked

What did you see instead?

RFCs were not automatically linked

This was a really nice feature of godoc!

@gopherbot gopherbot added this to the Unreleased milestone Mar 25, 2020
@gopherbot gopherbot added the pkgsite label Mar 25, 2020
@dmitshur dmitshur changed the title RFCs are not automatically linked automatically link RFCs in package documentation Mar 25, 2020
Copy link

@FiloSottile FiloSottile commented Apr 28, 2020

I'd love this! BTW, the new official home of RFC is, with links like

@julieqiu julieqiu added help wanted and removed Documentation labels Jun 15, 2020
@julieqiu julieqiu changed the title automatically link RFCs in package documentation x/pkgsite: automatically link RFCs in package documentation Jun 15, 2020
Copy link

@gopherbot gopherbot commented Jun 23, 2020

Change mentions this issue: x/pkgsite: link RFCs in package documentation.

Copy link

@dmitshur dmitshur commented Jun 23, 2020

In, @shaqque asked:

Currently does not support RFCxxxx (i.e. without space/s between "RFC" and the number). Should we also consider linking that?

I think we want to strike a good balance of being opinionated, so that it incentivizes people to write higher quality, consistent documentation, but not too opinionated where we are unnecessarily strict in a way that isn't helpful to humans.

The Go tree is heavily consistent at preferring including a space. There are 700 matches for [\s]RFC[\s][\d] (with space), and 55 for [\s]RFC[\d] (no space), many of which are references to time package's RFC3339 and such.

In my opinion, based on data I see now, it would be safe to start with requiring a space, but if we learn over time that it would be net positive to also accept the no-space version, we can add that later.

@FiloSottile may know if there's a spec that requires a space to be present or provides other guidance on what syntax to match precisely.

@dmitshur dmitshur added the NeedsFix label Jun 23, 2020
Copy link

@shaqque shaqque commented Jun 23, 2020

This appears to be documented in RFC 7322, Section 3.5 which states:

A citation/reference tag must not contain spaces.

Example: "[RFC2119]" rather than "[RFC 2119]"

However, the proper textual naming of an RFC contains a space.

Example: "See RFC 2119 [BCP14] for more information."
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
6 participants