b67443459a
The spec says that an embedded field must be specified as a type name (or a pointer to a type name). This is explicit in the prose and the FieldDecl syntax. However, the prose on promoted methods required a named type (originally the term used for a "defined type"). Before the introduction of alias types, type names could only refer to named/defined types, so the prose was ok. With the introduction of alias types in Go 1.9, we distinguished between defined types (i.e., types given a name through a type declaration) and type aliases (types given an alternative name), and retired the notion of a named type since any type with a name (alias type and defined type) could be considered a "named type". To make things worse, with Go 1.18 we re-introduced the notion of a named type which now includes predeclared types, defined types, type parameters (and with that type aliases denoting named types). In the process some of the wording on method promotion didn't get updated correctly. At attempt to fix this was made with CL 406054, but while that CL's description correctly explained the intent, the CL changed the prose from "defined type" to "named type" (which had the new meaning after Go 1.18), and thus did not fix the issue. This CL fixes that fix by using the term "type name". This makes the prose consistent for embedded types and in turn clarifies that methods of embedded alias types (defined or not) can be promoted, consistent with the implementation. While at it, also document that the type of an embedded field cannot be a type parameter. This restriction has been in place since the introduction of type parameters with Go 1.18 and is enforced by the compiler. Fixes #66540. For #41687. Change-Id: If9e6a03d7b84d24a3e6a5ceda1d46bda99bdf1f4 Reviewed-on: https://go-review.googlesource.com/c/go/+/603958 Reviewed-by: Ian Lance Taylor <iant@golang.org> TryBot-Bypass: Robert Griesemer <gri@google.com> Reviewed-by: Robert Griesemer <gri@google.com> Reviewed-by: Alan Donovan <adonovan@google.com> Reviewed-by: Axel Wagner <axel.wagner.hh@googlemail.com> |
||
|---|---|---|
| .. | ||
| initial | ||
| next | ||
| asm.html | ||
| go1.17_spec.html | ||
| go_mem.html | ||
| go_spec.html | ||
| godebug.md | ||
| README.md | ||
Release Notes
The initial and next subdirectories of this directory are for release notes.
For developers
Release notes should be added to next by editing existing files or creating
new files. Do not add RELNOTE=yes comments in CLs. Instead, add a file to
the CL (or ask the author to do so).
At the end of the development cycle, the files will be merged by being concatenated in sorted order by pathname. Files in the directory matching the glob "*stdlib/*minor" are treated specially. They should be in subdirectories corresponding to standard library package paths, and headings for those package paths will be generated automatically.
Files in this repo's api/next directory must have corresponding files in
doc/next/*stdlib/*minor.
The files should be in the subdirectory for the package with the new
API, and should be named after the issue number of the API proposal.
For example, if the directory 6-stdlib/99-minor is present,
then an api/next file with the line
pkg net/http, function F #12345
should have a corresponding file named doc/next/6-stdlib/99-minor/net/http/12345.md.
At a minimum, that file should contain either a full sentence or a TODO,
ideally referring to a person with the responsibility to complete the note.
If your CL addresses an accepted proposal, mention the proposal issue number in
your release note in the form /issue/NUMBER. A link to the issue in the text
will have this form (see below). If you don't want to mention the issue in the
text, add it as a comment:
<!-- go.dev/issue/12345 -->
If an accepted proposal is mentioned in a CL but not in the release notes, it will be flagged as a TODO by the automated tooling. That is true even for proposals that add API.
Use the following forms in your markdown:
[http.Request] # symbol documentation; auto-linked as in Go doc strings
[Request] # short form, for symbols in the package being documented
[net/http] # package link
[#12345](/issue/12345) # GitHub issues
[CL 6789](/cl/6789) # Gerrit changelists
To preview next content in merged form using a local instance of the website, run:
go run golang.org/x/website/cmd/golangorg@latest -goroot=..
Then open http://localhost:6060/doc/next. Refresh the page to see your latest edits.
For the release team
The relnote tool, at golang.org/x/build/cmd/relnote, operates on the files
in doc/next.
As a release cycle nears completion, run relnote todo to get a list of
unfinished release note work.
To prepare the release notes for a release, run relnote generate.
That will merge the .md files in next into a single file.
Atomically (as close to it as possible) add that file to _content/doc directory
of the website repository and remove the doc/next directory in this repository.
To begin the next release development cycle, populate the contents of next
with those of initial. From the repo root:
> cd doc
> cp -R initial/ next
Then edit next/1-intro.md to refer to the next version.