Adding please to a large repo - how to migrate to please and best practices for upkeep about please HOT 3 OPEN

Yup! You should mostly be able to run puku sync -w to generate all the third party stuff, and then run puku fmt ... to generate all the first party build files. We haven't built automated workflows to manage drift between the go.mod and third_party/go/BUILD yet but it's on the cards.

To get this to work nicely I recommend adding the following config options:

[Plugin "go"]
ModFile = //:modfile ; a filegroup for your go.mod file. This allows Please to resolve third party deps the same way as go_repo
TestRootCompat = true ; makes go_test run the test with the same working directory as `go test`

4. Do I need to create a BUILD file in each subpackage dir?

Yes. Puku can do this for you though.

5. What about needing to add go_test entries? Are these necessary for please and what would I miss out if I don't generate them?

Please tests provide a lot of control that go test can't. Internally, we run full e2e tests against our gRPC microservices, spinning up kafka, postgres, etc. all inside a go_test(), but this only works on linux where tests are run in a sandbox. You can see a slightly less advanced version of this for puku where we run e2e tests here:
https://github.com/please-build/puku/tree/master/e2e

This doesn't use sandboxes but still uses please to manage all the test deps. You can see what's going on there with plz test --shell //e2e/tests/codegen:codegen_test, and have a look at how this is set up here:
https://github.com/please-build/puku/blob/master/e2e/build_defs/e2e.build_defs

from please.

Hi, I read the Puku documentation and also looked at the implementation itself, but I'm still having trouble getting this working. I think the problem I am running into is that we don't have a top-level go.mod, and the examples seem to assume there is one.

At the top level of my repo I currently have a BUILD file:

subinclude("///go//build_defs:go")

filegroup(
    name = "first_binary",
    srcs = ["first_binary"],
    visibility = ["PUBLIC"],
)

and the .plzconfig has:

[Plugin "go"]
Target = //plugins:go
; a filegroup for your go.mod file. This allows Please to resolve third party deps the same way as go_repo
ModFile = //:gomod
; makes go_test run the test with the same working directory as `go test`
TestRootCompat = true

running sync gives me:

$ plz puku sync
00:02:15 CRITICAL exit status 1
00:02:15.559   ERROR: //:gomod failed:
Parsed build file BUILD but it doesn't contain target gomod
Build stopped after 20ms. 1 target failed:
    //:gomod
Parsed build file BUILD but it doesn't contain target gomod

I don't really understand the syntax for ModFile. What should I do if I have two projects in the mono repo, with different dependencies? For example, first_binary and second_binary? Each of those would have their own go.mod, and there wouldn't necessarily be one in the top level directory right?

from please.

You can remove that config entirely and it will try and resolve dependencies itself. The go_repo rules really do work better with a go.mod file, though, as without it we can't resolve the build list (list of resolved modules) consistently. Internally, we have a dummy one under //third_party/go that we use to resolve dependencies, but technically you can go without. You may just have to pass in modules via requirements = ["github.com/example/module"], to help resolve imports to the correct module path.

I've made a small update to the docs to make it clearer that that step is optional. Let me know if that makes more sense.

from please.