design: add metadata to all design documents

[perillo]

Today a gopher on Telegram reported a problem when trying to install staticcheck with go1.16.
Here is the error:

go1.16.12 install honnef.co/go/tools/cmd/staticcheck@latest

.local/lib/go/pkg/mod/honnef.co/go/tools@v0.3.0/go/ir/builder.go:36:2: //go:build comment without // +build comment

I remembered that there was a transition period, so I checked the original proposal https://go.dev/design/draft-gobuild.

Here is a list of problems:

1. The document is still marked as a draft
2. In the transition section, the text uses Go 1.(N−1), Go 1.N and so on.
   This is, IMHO, not very easy to follow.

I suggest to add metadata (like Python PEP) to all design documents, so that a reader can easily identify

• If the design has been accepted
• If the design has been implemented
• In what Go version the design has been implemented

Thanks.

[dmitshur]

The conversion to //go:build constraints was Go proposal 41184, which stated:

I propose that we adopt this design, with N = 17 in the Transition section, meaning that the prep work would happen in Go 1.16, the main change would land in Go 1.17, and the transition would be finalized in Go 1.18.

Does it work to start with the proposal first, which should have the information you're describing? Or do you still think design draft documents should be updated if they're used in a Go proposal? (If so, it seems this itself can be a proposal to establish that property.)

[ianlancetaylor]

@dmitshur I don't think we need to approve a proposal to update design docs. They are just documentation. A doc like https://go.dev/design/draft-gobuild should be updated to link to the proposal issue. Anybody can do that.

[perillo]

The conversion to //go:build constraints was Go proposal 41184, which stated:

I propose that we adopt this design, with N = 17 in the Transition section, meaning that the prep work would happen in Go 1.16, the main change would land in Go 1.17, and the transition would be finalized in Go 1.18.

Does it work to start with the proposal first, which should have the information you're describing? Or do you still think design draft documents should be updated if they're used in a Go proposal? (If so, it seems this itself can be a proposal to establish that property.)

Since a proposal is not always linked to a github issue, I think it is worth having common metadata in the document header.
This is useful both for historical reasons and for documentation (one example is the type-parameters proposal).

Thanks.

[ianlancetaylor]

I want to clarify that a proposal is always linked to a GitHub issue. However, in some cases design drafts were written and published before the GitHub issue was created, and nobody went back to add a link.

[ianlancetaylor]

If you have a specific suggestion for a metadata format, then I suppose that that should go through the proposal process as @dmitshur suggests. But I personally don't think it's necessary.

[gopherbot]

Timed out in state WaitingForInfo. Closing.

(I am just a bot, though. Please speak up if this is a mistake or you have the requested information.)