Add FAQ entries #40169
Add FAQ entries #40169
Conversation
| @@ -65,6 +65,31 @@ Currently the waiting period is as follows: | |||
|
|
|||
| ## FAQ | |||
|
|
|||
| #### Do I need to register a package to install it? | |||
There was a problem hiding this comment.
Content looks great, but I think the distinction between the two questions is so blurred that they could be merged into a single one
There was a problem hiding this comment.
Yeah, that's true. I wrote it like that at first actually and then split it up, since I thought that followed the style of the FAQ better. I think either way is OK though. If we add more to this one (like Lyndon's sugestions) then I have a preference for keeping them separate so that we don't have one giant entry.
README.md
Outdated
| #### Do I need to register a package to install it? | ||
|
|
||
| No, you can simply do `using Pkg; Pkg.add(url="https://github.com/JuliaLang/Example.jl")` | ||
| to e.g. install the package `Example.jl`, even if it was not registered. |
There was a problem hiding this comment.
It is worth saying here that if you register it people will be able to install it via pkg"add Example".
And maybe that they will be able to install it by activating a Project.toml that has it listed and running Pkg.resolve()
(in contrast to if it was installed via URL, in which case they would need a whole Manifest.toml)
There was a problem hiding this comment.
I expanded on this section a bit now
README.md
Outdated
| #### Should I register my package? | ||
|
|
||
| If you think your package might be useful to others, or provide functionality other | ||
| registered packages might want to rely on, go for it! |
There was a problem hiding this comment.
Saying registered pacakge here is a bit odd.
I think i kniw what yoiu are getting at, but i think clearer not to say that.
There was a problem hiding this comment.
should it be just "other packages"?
There was a problem hiding this comment.
Also some how explain that it needs to be registered to be a indirect dependency
There was a problem hiding this comment.
I think I was getting at the idea that registering is opting-in to the package ecosystem dependency tree, so if you think it's a useful leaf ("might be useful to others") or node (other packages might want to depend on it) then you should register. (And to favor those reasons over other reasons like "I want to claim the namespace" or "only I use it but I don't like copying the Manifest around")
README.md
Outdated
| If you think your package might be useful to others, or provide functionality other | ||
| registered packages might want to rely on, go for it! | ||
|
|
||
| It is easier for others to use your package if it has documentation that explains |
There was a problem hiding this comment.
Maybe the bit below this this should be it's own question.
"What should I do to before registering a package?"
Maybe it should just be dropped as beyond the scope of this document?
There was a problem hiding this comment.
hm, yeah. I meant this as kind of an elaboration on what does it mean to be useful to others. Like here's some ways you can help make it useful (and to encourage best practices).
I don't totally think it's beyond the scope of the document, because we do want packages in General to do these things. E.g. there's issues on RegistryCI for requiring X lines of tests (which IMO could also be "Y lines of README or docs"). So if it's in-scope to be a hard requirement, I think an earlier step is for it to be a soft recommendation and it should be in-scope for that.
There was a problem hiding this comment.
I tried to reword it a bit so it is hopefully more encouraging and also more direct
|
I'll merge this now so it doesn't dangle forever (e.g. if I forget this exists), but anyone feel free to do post-merge review and I'll try to address any feedback in follow-up PR(s). |
for "Do I need to register a package to install it?" and "Should I register my package?". I think the first is a somewhat common misconception with a short answer, and leads into the second, which provides us a place to briefly discuss the point of the General registry and point to docs/tests/ci to help new users learn how to make reliable and more broadly usable packages.
I know the README is already long and few read it, but I do think we should have this information somewhere, and it is specific to the General registry so I think this is the right place for it.
I saw a few things that could be removed from the README as well to shorten it, but I'll do that in a separate PR (edit: #40170).