design/freeze-syscall: new copy of syscall freeze proposal

This is a copy of the original text from a Google Doc.

Change-Id: If5ff705124ba36a5d73789b7e6e419f0dc72fc7c
Reviewed-on: https://go-review.googlesource.com/c/proposal/+/402415
Run-TryBot: Ian Lance Taylor <iant@google.com>
Reviewed-by: Ian Lance Taylor <iant@google.com>
Reviewed-by: Rob Pike <r@golang.org>
Auto-Submit: Ian Lance Taylor <iant@google.com>

1 files changed, 89 insertions, 0 deletions

diff --git a/design/freeze-syscall.md b/design/freeze-syscall.md
new file mode 100644
index 0000000..13fd9d4
--- /dev/null
+++ b/design/freeze-syscall.md
@@ -0,0 +1,89 @@
+# The syscall package
+
+Author: Rob Pike
+Date: 2014
+
+Status: this proposal was [adopted for the Go 1.4 release]
+(https://go.dev/doc/go1.4#major_library_changes).
+
+## Problem
+
+The `syscall` package as it stands today has several problems:
+
+1. Bloat. It contains definitions of many system calls and constants
+   for a large and growing set of architectures and operating systems.
+2. Testing. Little of the interface has explicit tests, and
+   cross-platform testing is impossible.
+3. Curation. Many change lists arrive, in support of wide-ranging
+   packages and systems. The merit of these changes is hard to judge,
+   so essentially anything goes. The package is the worst maintained,
+   worst tested, and worst documented package in the standard
+   repository, and continues to worsen.
+4. Documentation. The single package, called `syscall`, is different
+   for every system, but godoc only shows the variant for its own
+   native environment. Moreover, the documentation is sorely lacking
+   anyway. Most functions have no doc comment at all.
+5. Compatibility. Despite best intentions, the package does not meet
+   the Go 1 compatibility guarantee because operating systems change
+   in ways that are beyond our control. The recent changes to FreeBSD
+   are one example.
+
+This proposal is an attempt to ameliorate these issues.
+
+## Proposal
+
+The proposal has several components. In no particular order:
+
+1. The Go 1 compatibility rules mean that we cannot fix the problem
+   outright, say by making the package internal. We therefore propose
+   to freeze the package as of Go 1.3, which will mean backing out
+   some changes that have gone in since then.
+2. Any changes to the system call interface necessary to support
+   future versions of Go will be done through the internal package
+   mechanism proposed for Go 1.4.
+3. The `syscall` package will not be updated in future releases, not
+   even to keep pace with changes in operating systems it
+   references. For example, if the value of a kernel constant changes
+   in a future NetBSD release, package `syscall` will not be updated
+   to reflect that.
+4. A new subrepository, `go.sys`, will be created.
+5. Inside `go.sys`, there will be three packages, independent of
+   syscall, called `plan9`, `unix`, and `windows`, and the current
+   `syscall` package's contents will be broken apart as appropriate
+   and installed in those packages. (This split expresses the
+   fundamental interface differences between the systems, permitting
+   some source-level portability, but within the packages build tags
+   will still be needed to separate out architectures and variants
+   (darwin, linux)). These are the packages we expect all external Go
+   packages to migrate to when they need support for system
+   calls. Because they are distinct, they are easier to curate, easier
+   to examine with godoc, and may be easier to keep well
+   documented. This layout also makes it clearer how to write
+   cross-platform code: by separating system-dependent elements into
+   separately imported components.
+6. The `go.sys` repositories will be updated as operating systems
+   evolve.
+7. The documentation for the standard `syscall` package will direct
+   users to the new repository. Although the `syscall` package will
+   continue to exist and work as well as feasible, all new public
+   development will occur in `go.sys`.
+8. The core repository will not depend on the `go.sys` packages,
+   although it is likely some of the subrepositories, such as
+   `go.net`, will.
+9. As with any standard repository, the `go.sys` repository will be
+   curated by the Go team.  Separating it out of the main repository
+   makes it more practical to automate some of the maintenance, for
+   example to create packages automatically by exhaustive processing
+   of system include files.
+10. Any non-essential changes at tip that have occurred in the
+    `syscall` package since 1.3 will be migrated to the `go.sys`
+    subrepository.
+
+Note that we cannot clean up the existing `syscall` package to any
+meaningful extent because of the compatibility guarantee. We can
+freeze and, in effect, deprecate it, however.
+
+## Timeline
+
+We propose to complete these changes before the September 1, 2014
+deadline for Go 1.4.