docs: clarify target-directory vs. target: path composition#4
Merged
Conversation
…-directory
The e2e run caught a caller writing `target: docs/foo.md` alongside
`target-directory: docs` and getting a double-nested output path
(`docs/docs/foo.md`). The convention is documented implicitly ("target-
directory is where target: paths are resolved from") but easy to miss.
Adds a dedicated section explaining the composition rule with a real
example, the two common mistakes (repeating the prefix, absolute paths),
and a reminder that the target-directory scope is enforced by git add
regardless of what target: values individual entries choose.
Also tightens the inputs-table description of `target-directory` from
"Directory inside the target repo receiving the transformed files" to
call out the relative-path semantics up front.
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.
What
Adds an explicit section to
docs/action.mdon howtarget-directoryandtarget:compose:<target-repository>/<target-directory>/<target>.target:values intransformations.yamlare therefore relative totarget-directory, not to the target-repository root.target:, and using absolute paths.git add-scoped invariant is noted so readers understand why paths escapingtarget-directorydon't affect the target repo.Also tightens the inputs-table entry for
target-directoryto point at the new section.Why
The end-to-end run against the throwaway topology caught a caller that wrote
target: docs/e2e-fixture.mdalongsidetarget-directory: docs, producing adocs/docs/e2e-fixture.mdoutput path. The composition rule is documented implicitly today ("target-directory is where target: paths are resolved from"), but easy to skip past when copying an existingtransformations.yamlbetween callers.Verification
pnpm run lint,format:checkclean.Follow-up (not this PR)
Cutting
v0.1.0next. Existing callers pinning by SHA continue to work; the doc clarification lands regardless of the version tag.