Document the sibling signal list as an extension point - #2159
Merged
Conversation
Five comments and docstrings used `--' where the house style is a single dash. Nothing renders these as Markdown, so it was only an internal inconsistency, but it is the rule everywhere else.
`projectile-sibling-project-functions' is a plain list of functions, and adding your own is the intended way to teach Projectile a grouping it can't infer. The manual mentioned the option once, in passing, as the thing that fixes the order of the three built-ins - never that the list is yours to extend, and never what a function has to return. The worktree equivalent four sections down documents exactly that, so the omission was just an inconsistency. Adds a section with the contract, a worked example, and where to put yours relative to the built-ins. Also states something that was true but written down nowhere: the share cap is applied inside the two inferred signals rather than to the list as a whole, so a function you add is never capped. Someone writing one would reasonably assume the cap protects them. That note goes in the docstring too, which is where they'd actually look.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
projectile-sibling-project-functionsis a plain list of functions, and adding your own is the intended way to teach Projectile a grouping it can't infer - a workspace manifest, whatever your org uses to say which repos belong together. The manual mentioned the option exactly once, in passing, as the thing that fixes the order of the three built-ins. It never said the list is yours to extend, or what a function has to return.The worktree equivalent, four sections down the same page, spells all of that out. So this was just an inconsistency between two extension points of the same shape.
Adds a section with the contract, a worked example, and where to put yours relative to the built-ins.
It also writes down something that was true but recorded nowhere: the share cap is applied inside the two inferred signals rather than to the list as a whole, so a function you add is never capped - it's trusted the way a configured group is. Anyone writing one would reasonably assume the cap protects them. That note is in the docstring as well, since that's where they'd look first.
No CHANGELOG entry, matching how the other docs-only PRs this cycle were handled.