docs: Improve documentation for builtin VCL and pipe behavior

[SashankBhamidi]

This addresses issue #4372 by improving documentation for the built-in VCL, based on feedback from @nigoroll and @walid-git.

The changes are split into two commits:

1. docs: Document vcl_pipe default behavior change/843ef0f: Updates the user guide to explain that Varnish no longer pipes unknown methods by default. It adds examples for re-enabling pipe for specific methods or requests and clarifies how to view the builtin VCL with varnishd -x builtin.
2. docs: Explain extensible builtin subs concept in builtin.vcl/142d735: Adds a comprehensive comment block to the top of builtin.vcl explaining the two patterns for extending default behavior (vcl_builtin_* subs vs. vcl_req_* hooks).

[Copilot]

Pull request overview

This PR enhances documentation for Varnish's built-in VCL by clarifying extensible subroutines and explaining the change in default pipe behavior for unknown HTTP methods.

• Adds inline comments to builtin.vcl explaining that vcl_builtin_* subroutines can be overridden
• Documents the concept of "extensible subs" in the user guide
• Provides examples for re-enabling pipe mode for custom HTTP methods and WebSocket connections

Reviewed changes

Copilot reviewed 1 out of 2 changed files in this pull request and generated no comments.

File	Description
doc/sphinx/users-guide/vcl-built-in-code.rst	Adds explanation of extensible subs concept, mentions Git repository availability, and provides examples for re-enabling pipe mode in Varnish 8.0+
bin/varnishd/builtin.vcl	Adds consistent explanatory comments to all vcl_builtin_* subroutines indicating they can be overridden to change default behavior

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[nigoroll]

I have mixed feedback about this suggestion.

the pipe mode explanation makes sense, and I am 👍🏽 on it specifically

the explanation of the vcl_builtin_* subs looks like an improvement at first, but I am not sure how helpful it really is: The reference to the naming scheme is incomplete, and the main motivation is subtly different to the added explanation: All subs of the builtin.vcl can be overridden, that is the whole point of appending the built-in VCL to the user VCL. IIUC, the main point about the vcl_builtin_* subs is to make them available to calls from custom VCL, while subs like vcl_req_* allow specific extensions of parts of the built-in behavior only.

Repeating the same comment all over the place in the built-in VCL does not seem to make any sense to me at all because, again, there is nothing special about the possibility to override some subs, they can all be overridden.

Maybe @gquintard or @dridi should document their original design principles? My understanding might still not match what they had in mind (Ref: 3f3d67d)

Similar thing with the comment on git: Sure, all we do is available in git, but that is no news.

Regarding the overall structure of the PR, I would suggest to split out at least the pipe example into a separate commit.

[SashankBhamidi]

@nigoroll,

Thanks. About the repetitive comments in builtin.vcl. They were added with the intent to improve immediate discoverability at each sub.

I will rework the PR to:

• Remove those comments
• Refocus the documentation on the extensible sub design
• Split the pipe mode explanation into a separate commit

Pushing an updated version shortly.

[SashankBhamidi]

TIL rewriting Git history with --force doesn't trigger a GPG prompt requesting password. Didn't expect that!

[nigoroll]

Just a minor comment, otherwise I agree now.