More docs about to use go111 as a 1st gen runtime

[Shinta HATATANI]

The document of Go 1.11 seems not sufficient as a first generation runtime.

Originally, Go 1.11 runtime(standard) is released as a second generation runtime but it become to be listed as a first generation runtime.

Go 1.11 seems to become the last of first generation Go runtime which supports App Engine API and survive until first generation is terminated

because deprecation of Go 1.9 is announced and Go 1.12 is released as a second generation runtime which don't support App Engine API.

There is no description of App Engine API except in the Migrating your App Engine app from Go 1.9 to Go 1.11.

For example, if the application uses App Engine API, dev_appserver.py is needed but it is not documented.

It seems to be frequently discussed in this group.

I did sometime read Go 1.9 docs to use Go 1.11 runtime. Go 1.11 runtime docs is not self-contained.

I know the App Engine API will be gone in future and the migration to open API is strongly recommended but the migration is not low-hanging fruit as discussed in App Engine groups.

Some APIs don't yet have sufficient migrate paths.

For those who migrates from 1.9 to 1.11 needed immediately, description about maintaining apps using App Engine API is needed in short/middle term.

Please add more documents about features which are not recommended but yet supported.

[Chee How Chua]

On the documentation bit, I agree quite a lot. The documentation for the 1.11 runtime seems to be focused on helping current users migrate. For a new user, the documentation makes the whole thing look more complicated than it actually is.

I can imagine myself as a new user of App Engine that the lack of comprehensive documentation makes it difficult to get started on the platform.

The point about dev_appserver.py being needed but not documented is a huge mistake, unless the aim is to discourage new users of the platform.

For the 1.12 runtime, it is even inconsistent between the actual behaviour and the documentation. There is no discussion about developing for 1.12 locally - the dev_appserver.py script does not recognize the go112  directive, thus preventing the use of the script to start the server, which makes the documentation of serving the static files irrelevant. Granted, that it is not in a stable version, but perhaps that fact should be emphasized so that new users know what they are getting into.

I also find it curious why the use of the Datastore (currently called Cloud Firestore in Datastore mode) is encouraged but there is no UI for viewing the emulated Datastore.

[Jens-Uwe Mager]

I have a lot of dependencies on Memcache and the Mail api, so I do not see I can switch to the 1.12 or newer runtimes any time soon. Upon attempting to convert my older app engines to at least 1.11 I am really stuck. What makes the most headache for me (still unsolved) is that I have my app engine source in a bigger monorepo that holds all of the application code, not only the app engine stuff, which is traditionally only one subdirectory with a separate GOPATH for that project. Any attempts converting this to an 1.11 app with it is own main package have failed so far, my handlers are never being called when running using dev_appserver.py.