Please help with Go 1.16 release notes

[Dmitri Shuralyov]

Hi gophers,

Everyone has worked hard to make the upcoming Go 1.16 release the best one
yet—thank you! In addition to writing Go code, we need to communicate notable
changes to all the future Go 1.16 users so that our hard work doesn't go unseen.

There are currently 30 matches for "TODO" at https://tip.golang.org/doc/go1.16,
and we need your help to get to a complete draft of the Go 1.16 release notes,

which will unblock the Go 1.16 Beta 1 release.

I've recently made bite-sized issues for each distinct section that has outstanding TODOs:

https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3Arelease-blocker+milestone%3AGo1.16+label%3ADocumentation+%22doc%2Fgo1.16%3A%22+-label%3Arecurring

Some of you have already started closing them, but there are more available for the taking.

Gophers are great at concurrency, after all, so please jump in if you can!

• Pick some unassigned issue, and take ownership over its resolution if you can
• If the issue is still in NeedsInvestigation stage, suggest a possible wording to help move it to NeedsFix state
• If the issue is in NeedsFix state, mail a CL if that's all that's left to do
• Review existing CLs (find them at https://go-review.googlesource.com/q/project:go+status:open+doc/go1.16+label:Code-Review%253C%253D1)

Thank you again for your contributions, we really appreciate all of your help!

Dmitri

[Dmitri Shuralyov]

Thank you everyone for helping resolve all those TODOs so quickly!

It was great to see so many of you working effectively together, and

as a result we have a complete draft of the Go 1.16 release notes now.

There is still time to improve the draft from now until the final release,

so feel free to continue sending CLs if you spot any opportunities for

improvement, or if we missed something.

[ben...@gmail.com]

Looking good! The embed stuff and FS (and ReadDir!) look really good.

Under "File Systems", it links to https://tip.golang.org/pkg/io/fs/#FS, which mentions io/fsutil, but that package doesn't seem to exist. Typo, or is io/fsutil coming before release?

-Ben

[Tobias Klauser]

On Sunday, 13 December 2020 at 21:20:46 UTC+1 ben...@gmail.com wrote:

Looking good! The embed stuff and FS (and ReadDir!) look really good.

Under "File Systems", it links to https://tip.golang.org/pkg/io/fs/#FS, which mentions io/fsutil, but that package doesn't seem to exist. Typo, or is io/fsutil coming before release?

This looks like an oversight. I've sent https://golang.org/cl/277377 with a fix.

Thanks!

[ben...@gmail.com]

Just a couple of comments about the release notes:

1) At https://tip.golang.org/doc/go1.16#minor_library_changes under path/filepath, the links to WalkDir and Walk are broken -- I believe they should be #WalkDir and #Walk instead of /WalkDir and /Walk.

2) I think it'd be great if there was an explicit mention of the new fs.ReadDir (or os.ReadDir) function and fs.DirEntry type, either under the "File Systems" heading or under "os" module. The FS interface is great, but fs.ReadDir/os.ReadDir add a new system-level ability (using ReadDirent or readdir on Unix and FindFirst/FindNext on Windows) to more efficiently walk directory trees without so many system calls to stat. A related improvement is mentioned under path/filepath.WalkDir, but the actual system-level enhancement is provided by fs.ReadDir/os.ReadDir and fs.DirEntry. Perhaps something like this under the "os" module heading:

The new _ReadDir_ function reads a directory and returns the entries as a slice of _DirEntry_ instances, which makes traversing a directory more efficient by avoiding an operating system "stat" call in many cases. The new (*File).ReadDir method also returns _DirEntry_ instances (not to be confused with the existing Readdir method, which returns FileInfo instances).

3) Scanning the "os" package docs for 1.16, it seems there are too many things listed as new in 1.16. For example, https://tip.golang.org/pkg/os/#File.Readdir is listed as new in 1.16, when it's not.

-Ben

[Ian Lance Taylor]

On Mon, Jan 25, 2021 at 12:17 AM ben...@gmail.com <ben...@gmail.com> wrote:
>
> Just a couple of comments about the release notes:
>
> 1) At https://tip.golang.org/doc/go1.16#minor_library_changes under path/filepath, the links to WalkDir and Walk are broken -- I believe they should be #WalkDir and #Walk instead of /WalkDir and /Walk.
>
> 2) I think it'd be great if there was an explicit mention of the new fs.ReadDir (or os.ReadDir) function and fs.DirEntry type, either under the "File Systems" heading or under "os" module. The FS interface is great, but fs.ReadDir/os.ReadDir add a new system-level ability (using ReadDirent or readdir on Unix and FindFirst/FindNext on Windows) to more efficiently walk directory trees without so many system calls to stat. A related improvement is mentioned under path/filepath.WalkDir, but the actual system-level enhancement is provided by fs.ReadDir/os.ReadDir and fs.DirEntry. Perhaps something like this under the "os" module heading:
>
> The new _ReadDir_ function reads a directory and returns the entries as a slice of _DirEntry_ instances, which makes traversing a directory more efficient by avoiding an operating system "stat" call in many cases. The new (*File).ReadDir method also returns _DirEntry_ instances (not to be confused with the existing Readdir method, which returns FileInfo instances).
>
> 3) Scanning the "os" package docs for 1.16, it seems there are too many things listed as new in 1.16. For example, https://tip.golang.org/pkg/os/#File.Readdir is listed as new in 1.16, when it's not.

Thanks. I believe that all of these issues are now addressed.

Ian

[Ben Hoyt]

Thanks. 1) and 2) are fixed (excellent level of detail there, thanks). Still looks like 3) is an issue, though, as File.Readdir is still marked as new in 1.16.

[Ian Lance Taylor]

On Mon, Jan 25, 2021 at 4:22 PM Ben Hoyt <ben...@gmail.com> wrote:
>
> Thanks. 1) and 2) are fixed (excellent level of detail there, thanks). Still looks like 3) is an issue, though, as File.Readdir is still marked as new in 1.16.

Sorry, I should have read more closely. I don't think that
os.File.Readdir is reported as new in the 1.16 release notes. What is
correctly reported as new is os.File.ReadDir. Note the change in case
in the second 'd'. That is, we now have both os.File.Readdir and
os.File.ReadDir. Please let me know if I misunderstand. Thanks.

Ian

[Dmitri Shuralyov]

This is coming from our api/go1.16.txt file:

https://github.com/golang/go/blob/cf263e9f772eeeac21df6fe8f51a8c93e8ad5a27/api/go1.16.txt#L372-L373

Maybe Readdir shows up in go1.16.txt (in addition to go1.txt) because it now returns fs.FileInfo, an alias to os.FileInfo. I'll take a closer look.

--
You received this message because you are subscribed to a topic in the Google Groups "golang-dev" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/golang-dev/gsoj5Vv15j0/unsubscribe.
To unsubscribe from this group and all its topics, send an email to golang-dev+...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/golang-dev/CAOyqgcWUNMUHw8ZwYN1eHtU5_PJ0RNcFqYRXXk7WV5FB_m2qdg%40mail.gmail.com.

[Ben Hoyt]

Thanks Dmitri. Yeah, that explanation seems likely.

Ian, to clarify, it's the "1.16" that's showing up to the right of (*File).Readdir (lowercase d) here that I think is incorrect: https://tip.golang.org/pkg/os/#File.Readdir, because (*File).Readdir existed prior to 1.16 (as shown in the 1.15 docs here: https://golang.org/pkg/os/#File.Readdir).

-Ben

[Ian Lance Taylor]

On Mon, Jan 25, 2021 at 4:36 PM Ben Hoyt <ben...@gmail.com> wrote:
>
> Thanks Dmitri. Yeah, that explanation seems likely.
>
> Ian, to clarify, it's the "1.16" that's showing up to the right of (*File).Readdir (lowercase d) here that I think is incorrect: https://tip.golang.org/pkg/os/#File.Readdir, because (*File).Readdir existed prior to 1.16 (as shown in the 1.15 docs here: https://golang.org/pkg/os/#File.Readdir).

Ah, I see. I would also assume that that is happening because the
signature changed. Thanks.

[Dmitri Shuralyov]

As far as I can tell, the api/go*.txt files are okay;

the issue is is in how x/tools/godoc uses them.

Opened golang.org/issue/44081 and sent CL 289089.

After it goes through review, I'll update golang.org too.