docs: there may be multiple BUILD files in a directory

[AlexTereshenkov]

Docs rendered locally:

[huonw]

Thanks for improving the documentation! I think that we should be careful with how we phrase this: I think that for most users, having everything in one BUILD file works best, and trying to split an individual file up is likely to just cause confusion. It seems reasonable to describe that it is possible, though.

A couple of questions:

1. Do you use this in practice?
2. The BUILD.experimental example sounds good; maybe we could use that as the only example?
3. Maybe we could also add an info/warning box that explicitly suggests that "one BUILD is usually what you want", too?

[kaos]

Thanks for improving the documentation! I think that we should be careful with how we phrase this: I think that for most users, having everything in one BUILD file works best, and trying to split an individual file up is likely to just cause confusion. It seems reasonable to describe that it is possible, though.

I agree with ☝🏽

A couple of questions:

1. Do you use this in practice?

See this thread: https://chat.pantsbuild.org/t/16949338/is-there-a-way-to-exclude-an-arbitrary-build-target-at-runti#45196675-a2bb-4472-a837-e4de911f6898

2. The BUILD.experimental example sounds good; maybe we could use that as the only example?
3. Maybe we could also add an info/warning box that explicitly suggests that "one BUILD is usually what you want", too?

[cognifloyd]

1. Do you use this in practice?

I use this in the StackStorm repo to separate tool resolve requirements from the primary code requirements targets: https://github.com/StackStorm/st2/blob/master/BUILD.tools https://github.com/StackStorm/st2/blob/master/BUILD

[AlexTereshenkov]

Thanks for improving the documentation! I think that we should be careful with how we phrase this: I think that for most users, having everything in one BUILD file works best, and trying to split an individual file up is likely to just cause confusion. It seems reasonable to describe that it is possible, though.

A couple of questions:

1. Do you use this in practice?

2. The `BUILD.experimental` example sounds good; maybe we could use that as the only example?

3. Maybe we could also add an info/warning box that explicitly suggests that "one `BUILD` is usually what you want", too?

I am sorry for the late reply.

1. Do you use this in practice?

Yes, I do. We have some targets that I only want to become available at CI builds as there is some code generation done before Pants runs.

2. The `BUILD.experimental` example sounds good; maybe we could use that as the only example?

Definitely, I've updated the docs.

3. Maybe we could also add an info/warning box that explicitly suggests that "one `BUILD` is usually what you want", too?

I've added a sentence at the beginning of the paragraph to make it clearer.