docs: Explain in greater depth what content packages should include #3472
+214
−52
Conversation
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
with examples and cross-references to particular definitions. This should help to prevent misunderstandings with the connection between the `package.exclude` key in the manifest and this repository.
which previously pointed to nonexistent document sections.
elegaanz
reviewed
Nov 17, 2025
Member
elegaanz
left a comment
elegaanz
left a comment
There was a problem hiding this comment.
Thanks for writing this, I think it is an improvement to be more explicit. I left a few comments, mostly nitpicking, but I think it would improve what you wrote a bit and make it more consistent with other documentation files.
I think it would be good to link to this file in the relevant section(s) of the existing docs, so that it is easier to discover for people who may need this extra information.
docs/contents.md
Outdated
|
|
||
| ## Imported package version (Stage 3) | ||
|
|
||
| This is the state of the package that users get when they `#import` your code. |
Member
There was a problem hiding this comment.
Maybe you should be explicit here and say that these files will be downloaded and stored in the local package cache?
Contributor
Author
There was a problem hiding this comment.
I've rephrased the sentence, do you think it's better now?
but keep the internal references to the file category definitions. Other documentation files don't have a ToC either, so there's no need to start this now.
instead of blindly copying pre-existing sentence fragments from other parts of the docs.
since the examples stand out from the regular text enough as they are. Heavy application of markup tends to distract from truly important points.
so the stages themselves stand out more. In future communications, this may make it easier to refer to which *stage* of a package certain things apply.
in a way that makes it clear that a) this is the *final* package content and b) this is what users actually get (download/store) when they `import` a package.
in addition to the bare file listing. This should give new packagers a better idea of how to transform from Stage 2 to Stage 3.
since the latter is more detailed explanation of the former, including examples and motivation behind the individual steps.
so users used to the previous docs layout (possibly with bookmarks in their browsers) can discover the new documentation more easily.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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.
with examples and cross-references to particular definitions. This should help to prevent misunderstandings with the connection between the
package.excludekey in the manifest and this repository.After publishing my last package I had to learn the hard way that I misunderstood parts of the "What to commit? What to exclude?" section. Now that I know what I did wrong, the documentation starts making sense. However, it wasn't clear to me before and I had read that section 3 or 4 times.
Here's a proposal for a more elaborate description of the connection between a packages original repository, the contents of a PR published here, and what the users finally downloads to their machine when compiling documents. I haven't yet embedded this into the existing documentation because I wanted to get feedback on whether you think this is helpful first.
Thank you in advance!